Cypress IO Typescript Example

This is an example project testing a few different sites

It showcases the use of:-

• Typescript
• The Cypress GUI tool
• The Cypress command line tool
• Cypress custom commands cy.foo()
• PageObject Models on a Login Site
• Resuable Web Selectors
• CircleCI integration
• Slack reporting
• Mochawesome for fancy HTML reporting
• DevTools console log output on test fail
• Integration with Cypress' Dashboard Service for project recording
• Docker to self contain the application and require no pre-requisites on the host machine, bar Docker.

Installation

• Clone the project

Local Installation

• Run cd e2e && npm install to install cypress in the e2e folder
• We can slot this into any project easily and isolate its dependencies from your project
• View the Makefile for available commands

Docker Installation

• Run make docker-build in the project
• View the Makefile for available docker commands

Configuration

The main cypress configuration file, is in the e2e folder

• cypress.json

It can contain configuration options applicable to all environments

Environment specific config files are stored in e2e/config/<environment.json>

These will override any configurations specific environment vars set in cypress.json

these can be set on the command line by

• --env configFile=<environment.json>

Currently supported environments are

• development
• production
• staging
• qa

If no option is provided is will default to the baseUrl defined in e2e/config.json

In order to setup development, you will need a website locally running and your URI_ROOT should be set.

export URI_ROOT=<your_root_url>

If you are using docker then please set your URI_ROOT in your docker-compose file, it is set in this example

        environment:
            - URI_ROOT=http://the-internet.herokuapp.com

If it's URI_ROOT is not, and you select --env configFile=development the application will error, and ask you to set it.

Running tests in Docker via Make

• make docker-build - Build the image
• make docker-test-local - Run the tests
• make docker-bash - Access the bash shell in the container

For more, see the Makefile

Running tests locally via Make

• make test-local
• make test-qa
• make test-staging
• make test-production

Direct from the command line

• npm run cypress:open - runs test via gui
• npm run cypress:run - run tests via command line
• --env configFile=<env> - select an environment specific config
• -s '<pathToFile>' path for the spec files you wish to run
  • -s 'cypress/integration/commands.spec.js' example

GUI - Any changes made to test files are automatically picked up by the GUI and executed, post file save

• make test-local-gui Opens the GUI with the development configuration selection
• make test-qa-gui Opens the GUI with the qa configuration selection

The GUI can be opened by npx cypress open but requires a --env configFile=<env> option in order to set the correct BaseURL

Reporting

• Videos of each run are stored in e2e/cypress/videos
• Screenshots of failing tests are stored in e2e/cypress/screenshots
• HTML Reports of test runs are generated with MochaAwesome are stored in e2e/cypress/reports
• One report is generated per spec file
• A report bundler is provided which will process each report in e2e/cypress/reports and combine them into a single HTML document with a random uuid title in e2e/mochareports
• The report bundler can be run with make combine-reports && make generate-report

combine-reports:
	npx mochawesome-merge cypress/reports/mocha/*.json > mochareports/report-$$(date +'%Y%m%d-%H%M%S').json

generate-report:
	npx marge mochareports/*.json -f report-$$(date +'%Y%m%d-%H%M%S') -o mochareports

• It can be published to an AWS S3 bucket with make publish-reports-s3
• To publish to a bucket, set the following env vars

 export BUCKET_NAME=<YOUR_BUCKET_NAME>
 export AWS_ACCESS_ID=<YOUR_AWS_ACCESS_ID>
 export AWS_SECRET_KEY=<YOUR_AWS_SECRET_KEY>

Typescript

• Spec (test) files are written as example.spec.ts and contained in e2e/cypress/integration
• There is a tsconfig.json file in the e2e folder
  • It includes the paths for the .ts files. If you add other paths for yours, include them here.
  • It contains the typescript options and includes the Cypress typings for code completion.
  • use visual studio code (if you aren't already) - it's free and comes feature packed.
• There is a tslint.json file in the e2e folder
  • Contains some rules for code linting
• Tests are compiled with webpack typescript pre-processor.
  • The config file is in e2e/webpack.config.js
  • It is loaded in e2e/cypress/plugins/index.js, hooking into cypress's on event.

CircleCI

This project is building in CircleCI and can be viewed at the following link

https://circleci.com/gh/YOU54F/cypress-docker-typescript

See the .circleci folder

• config.yml - Contains the CircleCI build configuration

Slack Reporting

A JS file has been written in order to publish results

• e2e/scripts/slack/slack-alert.js

It provides the following distinct message types

• Build Failure / Cypress error
• Test Failure
• Test Success

It provides the following information

• CircleCI Build Status
• Test Stats (Total Tests / Passes / Failures)
• Author with link to Github commit
• Branch name
• Pull Request number and link to PR (only if PR)

And the following build/test artefacts

• CircleCI Build Log button
• HTML Test report button (only on build success)
• Videos of test runs (one link per test)
• Screenshots of failed tests (one link per failing test)

You will need to set up a couple of things in order to use this.

First build a Slack app & create an incoming webhook

• https://api.slack.com/slack-apps

Set the following environment variables in your localhost or CI configuration

• $SLACK_WEBHOOK_URL - The full URL you created in the last step
• $SLACK_API_CHANNEL - The channel ref you wish to publish to (right-click on your channel and click copy link, check the link, its the digits after the last / )

Cypress Dashboard Recording

CircleCI builds pass in a CYPRESS_RECORD_KEY in order to publish the results to the Cypress Dashboard.

We run make test-record to set the --record flag and publish the results to the dashboard.

Scripted Runner

An example script is here as cli/spec/ts

A example of how you can use this script in your project to:-

• Run Cypress with Mochawesome & junit reporters
• Merge mochawesome reports with mochawesome-merge
• Construct a slack alert with the merged report, screenshots and videos

rm -rf ./cypress/reports/mocha && npx ts-node script.ts

// tslint:disable-next-line: no-reference
/// <reference path='./node_modules/cypress/types/cypress-npm-api.d.ts'/>
import * as CypressNpmApi from "cypress";
import {slackRunner}from "cypress-slack-reporter/bin/slack-alert";
// tslint:disable: no-var-requires
const marge = require("mochawesome-report-generator");
const { merge } = require("mochawesome-merge");
// tslint:disable: no-var-requires

CypressNpmApi.run({
  reporter: "cypress-multi-reporters",
  reporterOptions: {
    reporterEnabled: "mocha-junit-reporters, mochawesome",
    mochaJunitReportersReporterOptions: {
      mochaFile: "cypress/reports/junit/test_results[hash].xml",
      toConsole: false
    },
    mochawesomeReporterOptions: {
      reportDir: "cypress/reports/mocha",
      quiet: true,
      overwrite: true,
      html: false,
      json: true
    }
  }
})
  .then(async results => {
    const generatedReport =  await Promise.resolve(generateReport({
      reportDir: "cypress/reports/mocha",
      inline: true,
      saveJson: true,
    }))
    // tslint:disable-next-line: no-console
    console.log("Merged report available here:-",generatedReport);
    return generatedReport
  })
  .then(generatedReport => {
    const base = process.env.PWD || ".";
    const program: any = {
      ciProvider: "circleci",
      videoDir: `${base}/cypress/videos`,
      vcsProvider: "github",
      screenshotDir: `${base}/cypress/screenshots`,
      verbose: true,
      reportDir: `${base}/cypress/reports/mocha`
    };
    const ciProvider: string = program.ciProvider;
    const vcsProvider: string = program.vcsProvider;
    const reportDirectory: string = program.reportDir;
    const videoDirectory: string = program.videoDir;
    const screenshotDirectory: string = program.screenshotDir;
    const verbose: boolean = program.verbose;
    // tslint:disable-next-line: no-console
    console.log("Constructing Slack message with the following options", {
      ciProvider,
      vcsProvider,
      reportDirectory,
      videoDirectory,
      screenshotDirectory,
      verbose
    });
    const slack = slackRunner(
      ciProvider,
      vcsProvider,
      reportDirectory,
      videoDirectory,
      screenshotDirectory,
      verbose
    );
     // tslint:disable-next-line: no-console
     console.log("Finished slack upload")

  })
  .catch((err: any) => {
    // tslint:disable-next-line: no-console
    console.log(err);
  });

function generateReport(options: any) {
  return merge(options).then((report: any) =>
    marge.create(report, options)
  );
}

TODO

• Applitools Integration
• Convert the slack-alert bash file into to a .ts file (Github thinks this is a shell project - waaaaah) - and add some tests!
• publish to s3 bucket needs error handling, should exit each function gracefully if the directories are empty