- Features
- Setup
- Demo & example
- On-premise installation instructions
- Documentation
- Development
- Behind the scenes
- FAQ
- Additional Resources
- License
- run cypress tests in parallel without dashboard
- upload failure screenshots and videos to S3 bucket
- browse test results, failures, screenshots and video recordings
- run in light mode w/o persistency or with MongoDB storage attached
- on-premise self-hosted cypress dashboard - use your own infrastructure, own your data, no limitations
- Point Cypress to your service - set
https://sorry-cypress-demo-director.herokuapp.com/
asapi_url
of<cypress-root>/packages/server/config/app.yml
- Run multiple instances of
cypress run --parallel --record --key xxx --ci-build-id <buildId>
- See the the tests running in parallel ๐
Visit https://sorry-cypress-demo.herokuapp.com/ and see the alpha version of the web dashboard in action.
This demo is a free heroku instance, it takes a minute to spin it up when you first navigate.
You can reconfigure Cypress to use api_url: "https://sorry-cypress-demo-director.herokuapp.com/"
, run your tests and see the results appear in the dashboard.
Also consider the example with detailed example of parallelization.
- Run
docker-compose -f docker-compose.full.yml up
- Open the browser at http://localhost:8080/ to see the dashboard
This will start all 3 services on your local machine,
Reconfigure Cypress to use api_url: "http://localhost:1234/"
,
Run your tests cypress run --parallel --record --key xxx --ci-build-id <buildId>
and you will see the results appear in the dashboard. Those cypress tests will run in parallel without connecting to the official dashboard.
You will need to setup S3 to be able to upload failed test screenshots. Replace the credentials in
docker-compose.full.yml
after you've set up S3 bucket.
Each package has a Dockerfile - use it to build your own images.
Pre-built Docker images are available at https://hub.docker.com/u/agoldis.
Docker image tag corresponds to the git tag, while latest
points to the master
git branch.
Refer to docker-compose.full.yml
for example.
Moved to Wiki - Heroku Tutorial
๐ It takes just 5 minutes to deploy sorry-cypress
on AWS using AWS CloudFormation template, you're getting a "full" version of the service with:
- Parallelization
- GraphQL API
- Web Dashboard
- S3 bucket preconfigured for storing screenshots and video recordings
- MongoDB as a persistance layer
- Secure network configuration via AWS VPC
- Pre-configured log groups via AWS Cloudwatch
- Convenient access via AWS Load Balancer
Read more in Wiki - AWS Tutorial or just hit the button ๐๐ป
Find cypress installation path
$ DEBUG=cypress:* cypress version
...
# here it is
cypress:cli Reading binary package.json from: /Users/agoldis/Library/Caches/Cypress/3.4.1/Cypress.app/Contents/Resources/app/package.json +0ms
...
In my case it is: /Users/agoldis/Library/Caches/Cypress/3.4.1/Cypress.app/Contents/Resources/app/
Change the default dashboard URL
$ cat /Users/agoldis/Library/Caches/Cypress/3.4.1/Cypress.app/Contents/Resources/app/packages/server/config/app.yml
...
# Replace this with a URL of the alternative dashboard
production:
# api_url: "https://api.cypress.io/"
api_url: "http://localhost:1234/"
...
The repository consists of 3 packages - you can deploy them on your own infrastructure:
packages/director
- is a service that's responsibe for parallelization and saving test resultspackages/api
- is a GraphQL server that allows to read test run details and resultspackages/dashboard
- is a web dashboard (ReactJS)
The director
service is responsible for:
- paralellization and coordination of test runs
- saving tests results
- saving failed tests screenshots
When you launch Cypress on a CI environment with multiple machines, each machine first contacts the dashboard to get the next test to run.
The dashboard coordinates the requests from different machines and assigns tests to each.
That is what director
service does ๐
cd packages/director
npm install
npm run build
npm run start
# ...
Initializing "in-memory" execution driver...
Initializing "dummy" screenshots driver...
Listening on 1234...
By default, the service will start on port 1234
with in-memory execution driver and dummy
snapshots driver.
That is what running on https://sorry-cypress.herokuapp.com
- it is a stateless execution, that just parallelizes tests, but does not persist test results and does not upload screenshots of failed tests.
The service uses dotenv
package - to change the default configuration, create .env
file in service's root to set the default environment variables:
$ pwd
/Users/agoldis/sorry-cypress/packages/director
$ cat .env
PORT=1234
# DASHBOARD_URL is what Cypress client shows as a "Run URL"
DASHBOARD_URL="https://sorry-cypress.herokuapp.com"
# Read more about execution drivers below
EXECUTION_DRIVER="../execution/in-memory"
# Read more about screenshot drivers below
SCREENSHOTS_DRIVER="../screenshots/dummy.driver"
# Read more about record keys whitelist below
ALLOWED_KEYS="my_secret_key,my_another_secret_key"
The director
uses "drivers" that define different aspects of its functionality.
...is what drives the execution flow.
There're 2 "execution drivers" implemented:
Keeps the state of runs in-memory. That means that restarting the service wipes everything.
That's the simplest and most naive implementation.
If you just want to run the tests in parallel and not worry about storing test results.
The state - test runs and results - are persisted in MongoDB, thus, can be queried and displayed in a dashboard.
To enable this driver, set the envrionment variables:
EXECUTION_DRIVER="../execution/mongo/driver"
MONGODB_URI="monodgb://your-DB-URI"
MONGODB_DATABASE="your-DB-name"
With MongoDB driver you can use the other services - api
and dashboard
to see the results of your runs.
...is what allows you to save the snapshots and videos tests.
It provides the client (Cypress runner) a URL for uploading the assets (videos and screenshots).
Is the default driver and it does nothing - snapshots won't be saved.
Set the environment variable to define the screenshots driver.
SCREENSHOTS_DRIVER="../screenshots/dummy.driver"
S3 screenshots driver documentation has moved to Wiki
Setting ALLOWED_KEYS variable allows you to define list of comma delimited record keys (provided to the Cypress Runner using --key
option) which are accepted by the director
service. This can be useful when Cypress is running on external CI servers and we need to expose director
to the internet.
Empty or not provided variable means that all record keys are allowed.
ALLOWED_KEYS="my_secret_key"
...is a simple GraphQL service, that allows to query the data persisted by MongoDB.
Set environment variables that define MongoDB connection details:
MONGODB_URI='mongodb://mongo:27017'
MONGODB_DATABASE='sorry-cypress'
...is a web dashboard implemented in ReactJS. It is in alpha stage and still very naive - you can explore test details, failures and see screenshots.
In production mode you will need to provide environment variable GRAPHQL_SCHEMA_URL
- graphql client will use the URL to download the schema.
Set environment variable that defines the URL for getting the schema:
GRAPHQL_SCHEMA_URL=https://sorry-cypress-demo-api.herokuapp.com
You can explore currently available features at https://sorry-cypress-demo.herokuapp.com/.
The project uses yarn workspaces, bootstrap everything by running yarn
in the root directory.
Run each package in development mode: yarn dev
.
It is recommended to use docker-compose
to run the backend services (director
and api
) and to run the dashboard
on host machine.
The project uses docker-compose
to conveniently run backend services in dockerized containers.
Run docker-compose build
from the project's root directory
Run docker-compose up
to start the services
The latter command will create 3 services:
- MongoDB instance on port
27017
director
service on port1234
api
service on4000
You can change the configuration using the environment variables defined in docker-compose.yml
file.
- Each machine sends the same initial request with:
- specs lists
- machine hardware details
- git commit details
--ci-build-id
and other CLI parameters
-
The
director
creates or fetches an existingrun
, based on the parameters and responds with a randomly generatedmachineId
and the allocatedrunId
-
Each cypress client requests a next available task for the
runId
which was returned previously -
The service looks at the list of specs and returns next available test
Original Cypress dashboard implements different "smart" strategies for picking the next test
- When there're no more available tests for a run, the service sends an "empty" response - client reports that it is finished
I was upset because:
- dashboard crashes and blocks my tests
- parallelization stops working after paid plan has reached its limit
Yes, Cypress is an open source software.
Yes.
- Wiki
- The official guide on Cypress parallelization
- CodeBuild configuration for running multiple Cypress Agents on AWS by @mlsad3
- CodeBuild configuration for running multiple Cypress Agents on AWS by @KyleThenTR
MIT