@spscommerce/e2e-core

sps-e2e-core

E2E test automation framework template based on Playwright, Jest and TypeScript.

Start the project depending on your use-case

1. If you start UI project from scratch -> go to the ds-react-seed repository and follow the instractions there.

2. If you already have your UI project set up -> add the current test automation project as a peer dependency to an existing one.

3. You can also put in a PR against this repo if you fix a bug or come up with an improvement! In order to achieve it, clone the current project and make a commit for a bug fix or feature implementation.

Initialize Node.js modules

Now it's time to npm install the node modules from package.json within the project's root directory:

npm install

Credentials

Create .credentials.sh file with your SPS credentials in the root directory:

export USER_EMAIL="EXAMPLE_USER"
export USER_PASSWORD="EXAMPLE_PASSWORD"
# Note: if USER_PASSWORD contains \ or " symbols, please add \ symbol before it.

Run:

source .credentials.sh

Run tests

HEADLESS=false BROWSER=chromium npm run test

CLI options

Variable	description	default	possible values
HEADLESS	launch browser in headless/headful mode	true	true, false
BROWSER	use + as a separator, e.g edge+firefox	chromium	chromium, firefox, webkit, edge
ENV	auth state is invoked for the defined env	test	test, prod
SLOWMO	slow down an execution for debugging	0	[number_in_ms]
TIMEOUT	global timeout for each test	30000	[number_in_ms]
WORKERS	number of workers (test threads)	number of CPUs minus 1	[number]
LOGGER	log all console errors, failed requests per test	false	true, false
TRACER	create Playwright actions trace info file per test	false	true, false
VIDEO	record a video for each test file	false	true, false
SUITE	if defined, report file name is created per suite	-	[string]

Run tests in Docker container

docker build -t ffui/e2e .

docker run -e USER_EMAIL -e USER_PASSWORD -it --rm --ipc=host --memory=6g --shm-size=1g ffui/e2e 

USER_EMAIL=[your_email] USER_PASSWORD=[your_pwd] xvfb-run --auto-servernum npm run test

Notes:

• --ipc=host is used since Chrome can run out of memory without this flag Docker doc
• --shm-size=1g is used since Docker runs a container with a /dev/shm shared memory space 64MB which is typically too small for Chromium and will cause Chromium to crash when rendering large pages
• --auto-servernum usage is recommended in order to run command with a random display number
• xvfb-run is used on Linux agents for headed execution since it requires Xvfb to be installed. Playwright official Docker image has Xvfb pre-installed

Trace Viewer

In order to show a trace file run the following commands:

cd [trace_file_path]

npx playwright show-trace [trace_file_name].zip

Detailed information could be found on Confluence.

Configuration files

Jest and jest-playwright config files were written in CommonJS style (not ESM). For more details, please check the following GH issues:

https://github.com/facebook/jest/issues/9430

https://github.com/playwright-community/jest-playwright/issues/718

Playwright configuration

Playwright (browser options) is configured in jest-playwright-config.js. More details about the Playwright configuration can be found here https://github.com/playwright-community/jest-playwright/#configuration.

Note: browsers are always launched incognito so that the browser retains no state at all including cookies, local database and caching

Jest configuration

Jest (test options) is configured in jest.config.js. More details about the Jest configuration can be found here https://jestjs.io/docs/configuration.

Global variables

• browserName <[string]> - name of the current browser channel (chromium, firefox or webkit)
• browser <[Browser]> - Playwright browser instance
• context <[Context]> - a new Playwright context instance for each new test file
• page <[Page]> - Playwright page instance (since a new context for every test file also creates a new page for it)

All of them are available globally in each Jest hook, test.

Usage with custom globalSetup

Custom globalSetup is set in jest.config.js and configured in jest.auth.js. An auth state is invoking one time via an API call in order to save it into a file and inject it into a new browser context created for each test suite.

Global test hooks

Jest global hooks are set in jest.config.js and configured in jest.setup.js. Global hooks are applied for each test suite before start. It is posible to override it for a specific suite directly in the test file.

Environment specific usage

If you want your tests to behave in a specific way in a certain test execution time, you can add a custom test environment which is set in jest.config.js and configured in jest-environment.config.js file. Here are some use-case examples when you probably need a custom environment:

• take a screenshot during the test failure
• delete log/trace file before test starts if it runs twice due to jest.retryTimes() option
• delete "heavy" trace file after test is finished successfully
• skip all further tests in suite if at least one test in suite is failed (applicable for a long-scenario test flows)

All the described use-cases were already implemented in the current project. You can remove it if you do not need it.

Usage with Typescript

Jest configuration in combination with ts-jest is defined in the transform option in jest.config.js. Types are used directly in tsconfig.json via types option.

Reports

Reporting is set and configured in jest.config.js. jest-junit creates compatible junit xml files (Azure test results friendly format).

Run tests in CI (Azure Pipelines)

In order to add an Azure Pipeline for your framework, head over to https://dev.azure.com/spscommerce/ and find your team. You can create a new pipeline by selecting your Git repository. For more information on getting started with Azure, visit https://github.com/SPSCommerce/azure-pipelines-config. Yaml file example is already included into the current project. Please edit it upon your needs. Detailed information could be found on Confluence.

Q&A

If you have any questions or difficulties with this template, reach out to us in #ffuiqa on Slack. Additional info over this template could be found on Confluence.

Used tools

• @types/jest - type definitions for Jest
• @types/jest-expect-message - type definitions for jest-expect-message
• @typescript-eslint/eslint-plugin - ESLint plugin which provides lint rules for TypeScript codebases
• @typescript-eslint/parser - ESLint parser which leverages TypeScript ESTree to allow for ESLint to lint TypeScript source code
• eslint - static code analysis tool
• eslint-plugin-jest - ESLint plugin for Jest
• eslint-plugin-jest-playwright - ESLint plugin for the Playwright testing needs
• jest - testing library for creating, structuring, running and asserting tests
• jest-junit - reporter that creates compatible junit xml files
• jest-circus - test runner that allows to bind to events via a custom environment
• jest-expect-message - ability to add a custom error message to the Jest assertions
• jest-playwright-preset - integrates Jest and Playwright
• node-fetch - light-weight module that brings Fetch API to Node.js
• playwright - browser automation tool
• typescript - language for application-scale JavaScript that adds optional types
• ts-jest - Jest transformer to test projects written in TypeScript