/browserstack-examples-cypress

This repository showcases the BrowserStack integration features with Cypress using the BrowserStack sample demo canonical app.

Primary LanguageTypeScript

Logo

BrowserStack Examples Cypress Cypress Mocha

Introduction

Cypress is a next generation front end testing tool built for the modern web. It addresses the key pain points developers and QA engineers face when testing modern applications. Mocha is a software tool that supports behavior-driven development (BDD).

This BrowserStack Example repository demonstrates a Cypress framework with parallel testing capabilities. The Cypress test scripts are written for the open source BrowserStack Demo web application (Github). This BrowserStack Demo App is an e-commerce web application which showcases multiple real-world user scenarios. The app is bundled with offers data, orders data and products data that contains everything you need to start using the app and run tests out-of-the-box.

The Cypress tests are run on different platforms like on-prem, docker and BrowserStack using various run configurations and test capabilities.

Repository setup

  • Clone the repository

  • Ensure you have the following dependencies installed on the machine

    • Cypress >= 6

    node:

    npm install

About the tests in this repository

This repository contains the following Cypress tests:

Module Spec name Spec Description
e2e end_to_end.spec.ts This scenario workflow verifies the complete and successful purchase product lifecycle steps on the e-commerce application. This scenario demonstrates the Page Object Model design pattern and is also the default spec executed in all the single spec run profiles.
login navigate_to_signin.spec.ts This scenario verifies whether Sign In page is displayed after clicking on Favourites.
login locked_user.spec.ts This scenario verifies the login workflow error for a locked user.
offers offers_for_mumbai.spec.ts This scenario mocks the GPS location for Mumbai and verifies that the product offers applicable for the Mumbai location are shown.
product filter_by_vendor.spec.ts This scenario verifies that only Apple and Samsung products are only shown when the Apple and Samsung vendor filter option is applied.
product sort_by_price.spec.ts This scenario verifies that the product prices are in ascending order when the product sort "Lowest to Highest" is applied.
user image_not_loading.spec.ts This scenario verifies that the product images load for user: "image_not_loading_user" on the e-commerce application. Since the images do not load, the test case assertion fails.
user existing_orders.spec.ts This scenario verifies that existing orders are shown for user: "existing_orders_user"
user add_to_favourites.spec.ts This scenario verifies that we are able to add favourites for user: "existing_orders_user"

Test infrastructure environments

Configuring the maximum parallel test threads for this repository

For all the parallel run configuration profiles, you can configure the maximum parallel test threads by changing the settings below.

  • BrowserStack

    In the config files in run_conf, we can set "parallels" : 5.

    Alternatively, we can even append a flag to the run commands: --parallels 5

Test Reporting

On Premise / Self Hosted

This infrastructure points to running the tests on your own machine using the Cypress test runner.

Running Your Tests

Run a specific test on your own machine

  • How to run the test?

    • To run the default test scenario (e.g. End to End Scenario) on your own machine, use the following command:
    npm run on-prem-default
    • To run a specific test scenario, use the following command with the spec file path as an argument:
    npm run on-prem "cypress/integration/<TEST_SUITE_NAME>/<SPEC_FILE_NAME>.spec.ts"

    Example:

    npm run on-prem "cypress/integration/user/existing_orders.spec.ts"

    where, the argument 'TEST_SUITE_NAME' can be any Cypress suite name configured in the integrations folder and 'SPEC_FILE_NAME' can be any of the spec files in that particular suite.

    E.g. "Login as username", "Login as Locked User", "Offers for mumbai geo-location" or any of the other test scenario names, as outlined in About the tests in this repository section.

  • Output

    This run profile executes a specific test scenario on a single browser instance on your own machine within the Cypress test runner.

Run the entire test suite on your own machine

  • How to run the test?

    To run the entire test suite on your own machine, use the following command:

    npm run on-prem-suite "cypress/integration/<TEST_SUITE_NAME>/**/*"

    Example:

    npm run on-prem-suite "cypress/integration/user/**/*"

  • Output

    This run profile executes the entire test suite sequentially on a single browser, on your own machine within the Cypress test runner.

Docker

Docker is an open source platform that provides the ability to package and test applications in an isolated environment called containers.

Prerequisites

  • Install and start Docker.
  • Note: Docker should be running on the test machine. Ensure Docker Compose is installed as well.
  • Run docker-compose pull from the current directory of the repository.

Running Your Tests

Run a specific test on the docker infrastructure

  • How to run the test?

    • To run the default test scenario (e.g. End to End Scenario) on docker, use the following command:
    npm run docker-default
    • To run a specific test scenario, use the following command with the spec file path as an argument:
    spec="cypress/integration/<TEST_SUITE_NAME>/<SPEC_FILE_NAME>.spec.ts" npm run docker

    Example:

    spec="cypress/integration/user/existing_orders.spec.ts" npm run docker

    where, the argument 'TEST_SUITE_NAME' can be any Cypress suite name configured in the integrations folder and 'SPEC_FILE_NAME' can be any of the spec files in that particular suite.

    E.g. "Login as username", "Login as Locked User", "Offers for mumbai geo-location" or any of the other test scenario names, as outlined in About the tests in this repository section.

  • Output

    This run profile executes a specific test scenario on a single browser deployed on a docker image.

Run the entire test suite using Docker

  • How to run the test?

    • To run the entire test suite on the docker image, use the following command:
    spec="cypress/integration/<TEST_SUITE_NAME>/**/*" npm run docker

    Example:

    spec="cypress/integration/user/**/*" npm run docker

  • Output

    This run profile executes the entire test suite on a single browser, deployed on a docker image.

BrowserStack

BrowserStack provides instant access to 2,000+ real mobile devices and browsers on a highly reliable cloud infrastructure that effortlessly scales as testing needs grow.

Prerequisites

  • Create a new BrowserStack account or use an existing one.

  • Identify your BrowserStack username and access key from the BrowserStack Automate Dashboard and export them as environment variables using the below commands.

    • For *nix based and Mac machines:
    export BROWSERSTACK_USERNAME=<browserstack-username> &&
export BROWSERSTACK_ACCESS_KEY=<browserstack-access-key>
    • For Windows:
    set BROWSERSTACK_USERNAME=<browserstack-username>
set BROWSERSTACK_ACCESS_KEY=<browserstack-access-key>

    Alternatively, you can also hardcode username and access_key objects in each of the config files in the run_conf folder.

Note:

  • We have configured a list of test capabilities in in each of the config files in the run_conf folder. You can certainly update them based on your device / browser test requirements.
  • The exact test capability values can be easily identified using the Browserstack Capability Generator

Running Your Tests

Run a specific test on BrowserStack

In this section, we will run a single test on Chrome browser on Browserstack. To change test capabilities for this configuration, please refer to the bstack-single.json file.

  • How to run the test?

    • To run the default test scenario (e.g. End to End Scenario) on a single BrowserStack browser, use the following command:
    npm run bstack-single-default
    • To run specific test scenario on a single BrowserStack browser, use the following command with the spec file path as an argument:
    npm run bstack-single --spec "cypress/integration/<TEST_SUITE_NAME>/<SPEC_FILE_NAME>.spec.ts"

    Example:

    npm run bstack-single --spec "cypress/integration/user/existing_orders.spec.ts"

    where, the argument 'TEST_SUITE_NAME' can be any Cypress suite name configured in the integrations folder and 'SPEC_FILE_NAME' can be any of the spec files in that particular suite.

    E.g. "Login as username", "Login as Locked User", "Offers for mumbai geo-location" or any of the other test scenario names, as outlined in About the tests in this repository section.

  • Output

    This run profile executes a single test on a single browser on BrowserStack. Please refer to your BrowserStack dashboard for test results.

Run the entire test suite in parallel on a single BrowserStack browser

In this section, we will run the tests in parallel on a single browser on Browserstack. To change test capabilities for this configuration, please refer to the bstack-single.json file.

  • How to run the test?

    To run the entire test suite in parallel on a single BrowserStack browser, use the following command:

    npm run bstack-parallel

    If you want to explicitly specifiy the number of parallel threads, then you can run it in the following way:

    npm run bstack-parallel --parallels 7

  • Output

    This run profile executes the entire test suite in parallel on a single BrowserStack browser. Please refer to your BrowserStack dashboard for test results.

Run the entire test suite in parallel on multiple BrowserStack browsers

In this section, we will run the tests in parallel on multiple browsers on Browserstack. To change test capabilities for this configuration, please refer to the bstack-parallel.json file.

  • How to run the test?

    To run the entire test suite in parallel on multiple BrowserStack browsers, use the following command:

    npm run bstack-parallel-browsers

[Web application hosted on internal environment] Running your tests on BrowserStack using BrowserStackLocal

Prerequisites

  • Clone the BrowserStack demo application repository.

    git clone https://github.com/browserstack/browserstack-demo-app

  • Please follow the README.md on the BrowserStack demo application repository to install and start the dev server on localhost.

  • In this section, we will run a single test case to test the BrowserStack Demo app hosted on your local machine i.e. localhost.

  • Note: You may need to provide additional BrowserStackLocal arguments to successfully connect your localhost environment with BrowserStack infrastructure. (e.g if you are behind firewalls, proxy or VPN).

  • Further details for successfully creating a BrowserStackLocal connection can be found here:

  • Before we execute the test, we need to download and start the binary as per the instructions mentioned in the link above.

[Web application hosted on internal environment] Run a specific test on BrowserStack using BrowserStackLocal

  • How to run the test?

    • In this section, we will run the default test on a single browser on Browserstack. To change test capabilities for this configuration, please refer to bstack-local-single.json file.

    • To run the default test scenario (e.g. End to End Scenario) using BrowserStackLocal, use the following command:

    npm run bstack-local-default
    • To run a specific test scenario on a single BrowserStack browser using BrowserStackLocal, use the following command with the spec file path as an argument:
    npm run bstack-local --spec "cypress/integration/<TEST_SUITE_NAME>/<SPEC_FILE_NAME>.spec.ts"

    Example:

    npm run bstack-local --spec "cypress/integration/user/existing_orders.spec.ts"

    where, the argument 'TEST_SUITE_NAME' can be any Cypress suite name configured in the integrations folder and 'SPEC_FILE_NAME' can be any of the spec files in that particular suite.

    E.g. "Login as username", "Login as Locked User", "Offers for mumbai geo-location" or any of the other test scenario names, as outlined in About the tests in this repository section.

  • Output

    This run profile executes a single test on an internally hosted web application on a single browser on BrowserStack. Please refer to your BrowserStack dashboard(https://automate.browserstack.com/) for test results.

[Web application hosted on internal environment] Run the entire test suite in parallel on a single BrowserStack browser using BrowserStackLocal

In this section, we will run the test cases to test the internally hosted website in parallel on a single browser on Browserstack. To change test capabilities for this configuration, please refer to the bstack-local-single.json file.

  • How to run the test?

    To run the entire test suite in parallel on a single BrowserStack browser using BrowserStackLocal, use the following command:

    npm run bstack-local-parallel

    If you want to explicitly specifiy the number of parallel threads, then you can run it in the following way:

    npm run bstack-local-parallel --parallels 7

  • Output

    This run profile executes the entire test suite on an internally hosted web application on a single browser on BrowserStack. Please refer to your BrowserStack dashboard for test results.

  • Note: By default, this execution would run maximum 5 test threads in parallel on BrowserStack. Refer to the section "Configuring the maximum parallel test threads for this repository" for updating the parallel thread count based on your requirements.

[Web application hosted on internal environment] Run the entire test suite in parallel on multiple BrowserStack browser using BrowserStackLocal

In this section, we will run the test cases to test the internally hosted website in parallel on multiple browsers on Browserstack. To change test capabilities for this configuration, please refer to the bstack-local-parallel.json

  • How to run the test?

    To run the entire test suite in parallel on a single BrowserStack browser using BrowserStackLocal, use the following command:

    npm run bstack-local-parallel-browsers

    If you want to explicitly specifiy the number of parallel threads, then you can run it in the following way:

    npm run bstack-local-parallel-browsers --parallels 7

  • Output

    This run profile executes the entire test suite on an internally hosted web application on multiple browsers on BrowserStack. Please refer to your BrowserStack dashboard for test results.

  • Note: By default, this execution would run maximum 5 test threads in parallel on BrowserStack. Refer to the section "Configuring the maximum parallel test threads for this repository" for updating the parallel thread count based on your requirements.

Generating Videos, Screenshots and Reports

  • Whenever a test is run on-prem or on docker, Mochawesome would automate generate reports in the cypress/report/mochawesome-report folder. Videos would be generated and stored in cypress/videos. Screenshots would be generated only for the failed tests and would be stored in cypress/screenshots.
  • When running a test on BrowserStack, such reports would be available in the results folder in HTML and JSON format.

Additional Resources

Open Issues

  • The test offers/offers_for_mumbai.spec.ts does not work due to a known and recognized issue from Cypress. More information can be found here.
  • Warning message Couldn't find tsconfig.json. tsconfig-paths will be skipped is seen because of an open issue which can be found here.