Skills & Knowledge

What You'll Need

Note

Clone the Project

If you would like to follow along with the course, using the exact sample code, you can use the example tests here.

Sauce Labs has developed a set of tools in conjunction with a command line tool called saucectl to enable test developers to get setup quickly to scale up their testing to more browsers and devices using the Sauce Labs Cloud, and to be able to do this with a wider range of testing frameworks than ever before.

This is a testing solution for developers that simplifies user setup, speeds up test execution time, unifies test results, and supports new open source frameworks like Playwright, Cypress, TestCafe, Espresso, and XCUI for running end-to-end web & mobile tests.

saucectl tools

Scalable Testing, Quickly

Installing with saucectl allows you to quickly and easily install all dependencies and start testing

What can saucectl and the Sauce Labs Platform Do?

saucectl stands for Sauce Control, the command line interface for running non-Selenium tests such a Cypress, TestCafe, Espresso, and XCUITest. The toolkit includes saucectl commands that allow you to interface with Sauce Labs, as well as the tools necessary to record the output from tests on a Sauce Labs Virtual Machine, making it easy to interpret, share and analyze those test results.

Why Use saucectl

Historically, most end-to-end testing consisted of various components such as Selenium, mocha-chai (test assertion frameworks), and other tools that are necessary to run, automate, and debug tests. Users would create a remote session to test a web application. With Sauce Labs saucectl and Cypress, you have an all-in-one test framework, runner, and assertion platform that doesn't require the client to send commands and wait for a response in order to run.

In other words, saucectl with Cypress provides a powerful clear-box testing tool that doesn't require downloading and installing several tools and libraries:

Testrunner Toolkit setup

Using Cypress alongside Sauce Labs also allow you to:

Testrunner Toolkit Sauce Labs dashboard

Two Ways to Run Tests

Sauce Mode

By default, when you use saucectl, it works by passing your entire test suite, including dependencies and configurations to Sauce Labs Cloud of Virtual Machines, where your tests will be executed as per your configurations. Use the command saucectl run or update mode: sauce in config.yml, to run your tests on Sauce Labs VMs.

Docker Mode

With saucectl, you can also install Docker and run a containerized version of your test environment, then pass the results to your Sauce Labs account, by setting mode: docker in config.yml.`

In this module, you will see how you can set up saucectl on Sauce Labs VMs or use saucectl along with Docker on your MacOS Computer. The basic steps include:

More detailed instructions are below

Video

Cypress and saucectl Setup

Download and Install saucectl

Next you need to download and install the saucectl Command Line Interface (CLI) that you will use to run Sauce Labs. This is a part of the Sauce Labs set of tools that allows you to set a configuration location & update the file in your local directory. There are several options (https://docs.saucelabs.com/testrunner-toolkit/installation) for installing it, and in this tutorial we will use npm, which means you need to have NodeJS installed on your machine.

It also allows you to run commands to run tests locally or remotely on the Sauce Labs platform.

First, anywhere on your machine install the saucectl tool globally, using this command npm to install the saucectl package:

npm i -g saucectl.

Cypress Test Code

You want to fork, clone or download a .zip copy of the example project, then place your tests in the cypress directory that contains your tests.

You have the following options to test out Cypress on Sauce:

Once you have a project directory containing cypress tests on your machine, navigate to the directory where the cypress.json and /cypress directory are, you can update the configuration file to run your tests.

Set Sauce Username and Access Key

You can access your Sauce Username and Access Key under [Account > User Settings]((https://app.saucelabs.com/user-settings). There are three ways you can configure your credentials with saucectl:

To manually configure your usename and access key, simply type the command:

saucectl configure

This command prompts you to manually enter your credentials, and will generate a credentials.yml file in a .sauce directory where you installed saucectl initially (in your home folder).

To find credentials.yml, search for a file called credentials.yml in a hidden directory (Cntrl + Shit + .) called .sauce.

the .sauce directory with credentials.yml

Visit accounts.saucelabs.com. You can create a free trial account if you haven't been assigned one.

Sauce Labs Account

Watch this video to see how to set up your Sauce username and access key as environment variables on your machine, or use the instructions here to set them up on Windows.

Initialize saucectl

Now that you have your Cypress test files set up in a directory, and your Sauce Labs username and access key setup globally with saucectl, you can initialize the test runner in order to run your Cypress tests on the Sauce Labs cloud.

From the folder where you should have placed cypress.json, and /cypress directory, and any other test files or assets, run the terminal command:

saucectl init

You will see a workflow appear allowing you to choose the data center you run tests in, the framework and version, configuration file, browser, platform, and options to download test assets.

Once you make all the choices in your workflow, you should be able to see the hidden /.sauce directory and the .sauceignore file in your project:

saucectl init workflow

The Configuration File

Once you have your project setup, open the project directory, take a look at the project files inside.

Project directory setup

You will see a cypress folder containing the /integrations directory where all test files are stored, as well as a cypress.json file where you can set options such as reporters, the base URL that tests will be run against, and more.

Another part of the package that was installed when you ran saucectl new is the /.sauce directory. The /.sauce directory has a .sauceignore file where you can designate the files and directories you don't want uploaded to Sauce Labs, and the config.yml file in which you will see something like the following (Config Docs):

The Config File

apiVersion: v1alpha
kind: cypress
sauce:
  region: us-west-1
  concurrency: 10
  metadata:
    tags:
      - e2e
    build: "$BUILD_ID"
rootDir: tests/e2e/
docker:
  fileTransfer: mount
cypress:
  version: 7.3.0
  configFile: "cypress.json"
suites:
  - name: "saucy test in docker"
    mode: docker
    browser: "chrome"
    config:
      env:
        hello: world
      testFiles: [ "**/*.*" ]

  - name: "saucy test in sauce"
    browser: "chrome"
    platformName: "Windows 10"
    config:
      env:
        hello: world
      testFiles: [ "**/*.*" ]

artifacts:
  download:
    when: always
    match:
      - console.log
    directory: ./artifacts/

Take a look at the top of the config file. There are several important elements here that can be modified.

.sauceignore

The sauceignore file that is essential to use to speed up your test runs. By default, everything that is in your project folder will be uploaded to Sauce Labs when you run your tests, however, it's important to include things like asset directories or other files that aren't necessary for a test run to this file.

Example :

cypress/videos/
cypress/results/
cypress/screenshots/
node_modules/
.git/
.github/
.DS_Store
__assets__
**/__assets__

Install Docker (Optional)

If you would like to run your tests in a Docker container and pass the results to the Sauce Labs platform, visit the docker download website and install the newest version of Docker on your machine.

Start up Docker to ensure it's running properly on your machine, and follow the instructions in the next module to modify config.yml to run tests in Docker Mode.

You can check to see if it's running with the command docker info, and see which version you have with the command docker -v.

See the next module for more about running tests with the command saucectl run

Running a Cypress test on sauce is easy. If you follow the configuration steps using saucectl init in the last module, all you need to do is run the command:

saucectl run

Specifying which tests you want to run in which environment can be configured in the suites: tab in the .sauce/config.yml file. This lesson will cover:

Running tests using Cypress and saucectl allows you to run as many combinations of tests and environments as you would like.

Video

Running Tests with Sauce and Cypress

Example Cypress Code

For example Cypress tests, you can:

Add and Run New Tests

As you grow your testing suite, you may want to add new tests to run, and you may want to have the option to run different specific groups of tests, and run on different browsers. The config: testFiles: objects under the suites: tag allow you to specify which tests are run, when:

If you used saucectl init the object test will automatically run any tests in the cypress/integration directory with a supported Cypress test file type and look something like this:

suites:
- name: cypress - windows 10 - chrome
  browser: chrome
  platformName: windows 10
  config:
    testFiles:
    - '**/*.*'
  mode: sauce
rootDir: .

Lets create two directories within your cypress/integration directory so that you can learn to specify both directories and files. Create both a /smoke and a /regression directory, and paste copies of your tests in each.

saucectl init workflow

You will want to modify any code that refers to the project structure that may change. In this example, you will want to update the imports in login.spec.js with an additional ../ to account for the re-organization:

saucectl init workflow

Now you can modify your config.yml to run one test from each directory. You will need to create two -name: objects under the suites:;

suites:
- name: cypress - windows 10 - chrome smoke
  browser: chrome
  platformName: windows 10
  config:
    testFiles:
    - 'smoke/*.spec.*'
  mode: sauce
- name: cypress - windows 10 - chrome regression
  browser: chrome
  platformName: windows 10
  config:
    testFiles:
      ['regression/*.test.*']

Note

Now when you use the command saucectl run you should see both test suites, chrome smoke and chrome regression having run:

saucectl init workflow

Run Your Tests in Different Browsers

Sauce Labs supports running Cypress tests in the environments that are supported by the Cypress test runner. This means you can run using the Chrome, Microsoft Edge, and Firefox browsers.

Run Your Tests in Different Modes

Run All Tests in One Mode

If you do not have the mode: specified anywhere in your .sauce/config.yml file, then, by default, all your tests will be bundled, and uploaded and run on the Sauce Labs Cloud of Virtual Machines.

If you would like to try running tests in Docker, you can set all your test suites to run, by default, in docker mode by setting the defaults: option:

apiVersion: v1alpha
kind: cypress
defaults:
  mode: docker
  # ...

You can change this setting back to default to Sauce mode by changing mode: sauce or delete the mode: option.

Unless you specify a different mode in a suite, all tests will run in Docker Mode:

Note

Run Certain Tests in Different Modes

You also have the ability to run some suites in Docker Mode, and some suites in Sauce Mode, all from the same test run, by setting individual suites to run in different modes.

To set the mode on the suite level, simply add the mode: option somewhere under your test suite name;

  suites:
    - name: saucy test suite
      mode: docker

The following settings in your config.yml file will run two of your tests in Docker Mode (by default) and two of your tests in Sauce Mode:

suites:
- name: cypress - windows 10 - chrome smoke
  mode: sauce
  browser: chrome
  platformName: windows 10
  config:
    testFiles:
    - 'smoke/*.spec.*'
- name: cypress - windows 10 - chrome regression
  browser: chrome
  platformName: windows 10
  config:
    testFiles:
      ['regression/*.test.*']
- name: cypress - windows 10 - firefox - all
  browser: firefox
  browserVersion: 86.0
  platformName: windows 10
  config:
    testFiles:
      - '**/*.*'
- name: cypress - windows 10 - edge -all
  browser: microsoftedge
  browserVersion: 90.0
  platformName: windows 10
  config:
    testFiles:
      - '**/*.*'
  mode: sauce

Now, when you run the command saucectl run, you should see output like this in your console:

Cypress Tests on Sauce

View Your Test Results

If you go to app.saucelabs.com, you should see the two tests on your automated test results dashboard:

Cypress Tests on Sauce

If you click into the tests, you can see the video of the test running on the Cypress client, and a log you can easily share with others:

Sauce Cypress Test Results

Once you have your tests running, learn more about what you can do with Sauce Labs and Cypress in Module 2

Final Code

See an example of the test suite with updated suites in .sauce/config.yml

All Specs passedAll Specs passed

Running Cypress tests in parallel on the Sauce Labs Cloud using the saucectl is as simple as updating a single field in your .sauce/config.yml file:

Sauce Cypress Test Results

Inside of the .sauce data object, find the concurrency field, and change it from 1 to a larger number (2 or 10)

You are able to run suites of tests in parallel using the concurrency field in config.yml, running as many test suites in parallel as you would like (limited by the of virtual machines you have available on your Sauce Labs account).

Run Parallel Tests in Multiple Browsers

Suites will automatically be run in parallel depending on your teams' allowed concurrency.

In this example, Login Chrome, Login Edge, and Login Firefox will have all the test files in each suite run in parallel on a different machine.

...
suites:
  # Chrome
  - name: "Login Chrome"
    browser: "chrome"
    platformName: "Windows 10"
    screenResolution: "1400x1050"
    config:
      testFiles: [ "**/login.*" ]
  # MicrosoftEdge
  - name: "Login MicrosoftEdge"
    browser: "edge"
    platformName: "Windows 10"
    screenResolution: "1400x1050"
    config:
      testFiles: [ "**/login.*" ]
 # Firefox
  - name: "Login Firefox"
    browser: "firefox"
    platformName: "Windows 10"
    screenResolution: "1400x1050"
    config:
      testFiles: [ "**/login.*" ]

To find out more about the names for the different browser and platform (OS) combinations, visit the platform configurator, and documentation for the most up to date config.

Final Code

See an example suite set to run in parallel on multiple browsers.

Go on to Module 2 if you have your Cypress Tests set up.

Sauce Labs' Testrunner Toolkit allows you to take existing Cypress test suites (or build a cypress test suite) and quickly run them on Sauce Labs. In this lesson, you will learn how to modify a couple settings in the cypress.json and .sauce/config.yml files, then write a basic test and run it on Sauce Labs.

Video

Create Page Objects For a Cypress Test

Note

Test Configuration

Cypress.json

Inside your testrunner-tests project file that you created, you will notice the cypress.json file. This file is used to set all kinds of options for your Cypress test. If you don't set any options, Cypress will use a set of default values. You can pull in data from this file into your tests, to make it easier to preload data in your test.

First, you will need to add information for your tests about the URL of the app you are testing against. Add the following line to cypress.json, which you will use in your tests to pull in the site you are testing against.

//filename: testrunner-tests/cypress.json
{
 "baseUrl": "https://www.saucedemo.com/v1/"
}

Constants.js

Next, in the cypress/support directory (create the cypress/support directory if it doesn't already exist) create a file called constants.js.

It's good practice to store sensitive information like a username and a password in a separate file so you can use a .gitignore file to exclude it from Github repositories you will commit your project to.

Open constants.js and add the following objects to store different login credentials:

// filename: cypress/support/constants.js
export const LOGIN_USERS = {
   LOCKED: {
       username: 'locked_out_user',
       password: 'secret_sauce',
   },
   STANDARD: {
       username: 'standard_user',
       password: 'secret_sauce',
   },
};

Now you can use these objects to login in your tests by calling LOGIN_USERS.LOCKED or LOGIN_USERS.STANDARD.

Create Page Objects Directory

After that Create a directory called pageobjects in the cypress/ directory. Typically, when you write tests you separate your code into items that control interactions with the page, or _page objects, _ or code that specifies what to test, or test objects.

You project should now look something like this:

Project structure with page objects

Create Login Page Object

Open the new pageobjects directory and add a file named: LoginPage.js, then open LoginPage.js and add the following: \

In LoginPage.js you will create several get methods to locate elements on the page you will use in your test later on:

// filename: cypress/pageobjects/LoginPage.js
class LoginPage {
   get screen() {
       return cy.get('#login_button_container');
   }

   get username() {
       return cy.get('#user-name');
   }

   get password() {
       return cy.get('#password');
   }

   get loginButton() {
       return cy.get('.btn_action');
   }

   get errorMessage() {
       return cy.get('[data-test="error"]');
   }

// ...

Since you have baseUrl specified in cypress.json, your tests know to visit a page that looks like https://www.saucedemo.com/v1/. The first get method locates the div in blue below, where the other elements are found.

Login Page elements

You can also see the ids, classes, and data-test element that your tests' get methods use to locate other elements on the page.

Next, below the get methods, add in the code to create your signIn method, and export the LoginPage class so it can be used by other classes (your test methods).

// filename: cypress/pageobjects/LoginPage.js
// ...


   signIn(userDetails) {
       const {password, username} = userDetails;

       if (username) {
           this.username.type(username);
       }
       if (password) {
           this.password.type(password);
       }

       this.loginButton.click();
   }
}

export default new LoginPage();

If you recall, in const.js there is a constant created called LOGIN_USERS which contains two objects, either LOCKED or STANDARD.

The signIn() method will allow you to pass either the LOCKED or STANDARD object in with the username and password values.

Later, when you call that method in your test, you will pass in the set of username and password fields from const.js depending on whether you call the method with signIn(LOGIN_USERS.STANDARD) or signIn(LOGIN_USERS.LOCKED).

Create Inventory Page Object

You will also need to create a page object for the second page in the login flow, the Inventory Test.

The inventory page

Create a new file in the cypress/pageobjects directory called SwagOverviewPage.js. Your project structure should look something like this:

Project structure with inventory page

Open SwagOverviewPage.js and copy in the following code:

//filename: cypress/pageobjects/SwagOverviewPage.js
class SwagOverviewPage {
    get screen() {
        return cy.get('.inventory_list');
    }
}
export default new SwagOverviewPage();

This will go to the sauce demo page that lists the products, and search for the div that contains the list of items with an id of inventory_list.

Final Code

See a sample of the project and code here.

Final Lesson CodeFinal Lesson CodeFinal Lesson CodeFinal Lesson Code

Now that you have all the configuration files and page objects created, you can create your first test object to use all of these elements and run a test.

Video

Write a Cypress Test

Write Your First Test

Now you will create a new test object In the cypress/integration directory, named login.spec.js. In accordance with Page Object Model (POM) conventions, you are creating separate directories for page and test objects.

Open login.spec.js and create the describe() method to set up your test. The cy.visit() method contains an empty string because it will automatically pull the baseUrl from the cypress.json file:

//filename: cypress/integrations/login.spec.js
import LoginPage from '../pageobjects/LoginPage';
import SwagOverviewPage from '../pageobjects/SwagOverviewPage';
import { LOGIN_USERS } from '../support/constants';

describe('LoginPage', () => {
   beforeEach(() => {
       cy.visit('');
   });
// ...

Next, add in an it() method, which is a Mocha/ Cypress standard for declaring test methods. This will check to see that when you get onto the page, the screen (Defined in LoginPage.js) element which contains the login field is visible.:

//filename: cypress/integrations/login.spec.js
import LoginPage from '../pageobjects/LoginPage';
import SwagOverviewPage from '../pageobjects/SwagOverviewPage';
import { LOGIN_USERS } from '../support/constants';

describe('LoginPage', () => {
   beforeEach(() => {
       cy.visit('');
   });

   it('should be able to test loading of login page', () => {
       LoginPage.screen.should('be.visible');
   });
// ...

Next, add a test to check that the next page (where you can choose items for your cart.) is visible when you log in with valid user credentials:

//filename: cypress/integrations/login.spec.js
import LoginPage from '../pageobjects/LoginPage';
import SwagOverviewPage from '../pageobjects/SwagOverviewPage';
import { LOGIN_USERS } from '../support/constants';

describe('LoginPage', () => {
   beforeEach(() => {
       cy.visit('');
   });

   it('should be able to test loading of login page', () => {
       LoginPage.screen.should('be.visible');
   });

   it('should be able to login with a standard user', () => {
       LoginPage.signIn(LOGIN_USERS.STANDARD);
       SwagOverviewPage.screen.should('be.visible');
   });

// ...

Finally, add one last it() method to create a test that will login in with invalid user credentials, and verify that the error message shows up:

//filename: login.spec.js
import LoginPage from '../pageobjects/LoginPage';
import SwagOverviewPage from '../pageobjects/SwagOverviewPage';
import { LOGIN_USERS } from '../support/constants';

describe('LoginPage', () => {
   beforeEach(() => {
       cy.visit('');
   });

   it('should be able to test loading of login page', () => {
       LoginPage.screen.should('be.visible');
   });

   it('should be able to login with a standard user', () => {
       LoginPage.signIn(LOGIN_USERS.STANDARD);
       SwagOverviewPage.screen.should('be.visible');
   });

   it('should not be able to login with a locked user', () => {
              LoginPage.signIn(LOGIN_USERS.LOCKED);
       LoginPage.errorMessage.should('have.text','Epic sadface: Sorry, this user has been locked out.');
   });
});

Final Code

See a sample of the project and code here

Final Lesson Code

It often helps to debug on your local machine, and the Cypress client provides some additional debugging features if you install it locally.

Video

Run and Debug A Cypress Test Locally

Install npm Packages

Install node package manager (npm) in the project folder by navigating to your project directory and running npm init to initialize it in your project.

What this does is install node package manager, which will allow you to install cypress on your machine so you can try running the tests locally first. When you do this, you will see a file called package.json, which you will need to update.

To install cypress locally, add dependencies: {} with cypress:"x.x.x" to the package.json file that was added:

{
  "name": "cypress-examples",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "keywords": [],
  "author": "Your Name",
  "license": "ISC",
  "dependencies": {
    "cypress": "5.6.0",
  }
}

Note

Now run npm install again to install the extra dependencies specified in package.json. Now in your folder you should see:

Project directory with npm

Run Cypress on Your Computer

Now you can save and run a local cypress test from your project directory in terminal using: npx cypress open

A new window will open on your machine, and you will see the Cypress client open up. You should see the tests from your cypress/integrations directory open up.

The Cypress Client

Click on login.spec.js, and you will see your tests run in a new window. Notice that if you make changes and save them to your code, your test window will update in real time.

Cypress Test Runner