Dashboard Service

Improve this doc

What you’ll learn

  • How to set up a project to have its tests recorded.
  • What you see in the Dashboard Service for recorded tests.
  • How to manage organizations, projects, and users in the Dashboard Service.

The Cypress Dashboard is a service that gives you access to recorded tests - typically when running Cypress tests from your CI provider. The Dashboard provides you insight into what happened when your tests ran.

Overview

The Dashboard allows you to:

  • See the number of failed, passing, pending and skipped tests.
  • Get the entire stack trace of failed tests.
  • View screenshots taken when tests fail or when using cy.screenshot().
  • Watch a video of your entire test run or a video clip at the point of test failure.
  • See how fast your spec files ran within CI including whether they were run in parallel.
  • See related groupings of tests.
  • Manage who has access to your recorded test data.
  • See usage details for each organization.
  • Pay for your selected billing plan.

See tests runs in the Test Runner

Additionally we’ve integrated the tests run into the Cypress Test Runner. This means you can see the tests run in the Runs tab from within every project.

Runs List

Have a question you don’t see answered here?

We have answered some common questions about the Dashboard Service in our FAQ..

Example projects

Once you log in to the Dashboard Service you can view any public project.

Here are some of our own public projects you can view:

Projects

With Cypress, you have the ability to record your project’s tests.

You typically want to record when running tests in Continuous Integration, but you can also record your tests when running locally.

Setup

To set up your project to record, you must use the Test Runner.

Make sure you install and open it first!

To set up a project to record:

Setup Project Screen

  1. Click on the Runs tab of your project within the Test Runner.
  2. You will need to log in to record your tests, so you may need to log in with GitHub here.
  3. Click Setup Project to Record.
  4. Fill in the name of your project (this is only for display purposes and can be changed later).
  5. Choose who owns the project. You can personally own it or select an organization you’ve created. Organizations work just like they do in GitHub. They enable you to separate your personal and work projects. Read more about organizations.
  6. Choose whether this project is Public or Private.
    • A public project can have its recordings and runs seen by anyone. Typically these are open source projects.
    • A private project restricts its access to only users you invite.
  7. Click Setup Project.
  8. Now you should see a view explaining how to record your first run.
  9. After setting up your project, Cypress inserted a unique projectId into your cypress.json. You will want to check your cypress.json into source control.
  10. Within Continuous Integration, or from your local computer’s terminal, pass the displayed Record Key while running the cypress run command.

    • Provide record key directly:

      cypress run --record --key <record key>
      
    • Or set record key as environment variable

      export CYPRESS_RECORD_KEY=<record key>
      
      cypress run --record
      

🎉 Your tests are now recording! As soon as tests finish running, you will see them in the Dashboard and in the Runs tab of the Test Runner.

Identification

Project ID

Once you set up your project to record, we generate a unique projectId for your project and automatically insert it into your cypress.json file.

The projectId is a 6 character string in your cypress.json:

{
  "projectId": "a7bq2k"
}

This helps us uniquely identify your project. If you manually alter this, Cypress will no longer be able to identify your project or find the recorded builds for it.

We recommend that you check your cypress.json including the projectId into source control. If you don’t want your projectId visible in your source code you can set it as an environment variable from your CI provider using the name CYPRESS_PROJECT_ID. The exact mechanism for doing so depends on your CI provider but could be as simple as:

export CYPRESS_PROJECT_ID={projectId}

Record key

Once you’re set up to record test runs, we automatically generate a Record Key for the project.

A record key is a GUID that looks like this:

f4466038-70c2-4688-9ed9-106bf013cd73

You can create multiple Record Keys for a project, or delete existing ones from our Dashboard. You can also find your Record Key inside of the Settings tab in the Test Runner.

Authentication

Cypress uses your projectId and Record Key together to uniquely identify projects.

The record key is used to authenticate that your project is allowed to record. As long as your record key stays private, nobody will be able to record test runs for your project - even if they have your projectId.

If you have a public project you should still keep your record key secret. If someone knows both your record key and your projectId, they could record test runs for your project - which would mix up all of your results!

Think of your record key as the key that enables you to write and create runs. However, it has nothing to do with being able to read or see runs once they are recorded.

If your Record Key is accidentally exposed, you should remove it and generate a new one from the Dashboard Service.

Public vs Private

  • Public means that anyone can see the recorded test runs for the project. It is similar to how public projects on Github, Travis CI, or CircleCI are handled. Anyone who knows your projectId will be able to see the recorded runs for public projects.

  • Private means that only users you invite to your organization can see its recorded runs. Even if someone knows your projectId, they will not have access to your runs unless you have invited them.

Transfer ownership

You can transfer projects that you own to another organization you are a part of or to another user in the organization. Projects can only be transferred from the Dashboard Service.

Transfer Project dialog

Delete

You can delete projects you own. This will also delete all of their recorded test runs. Deleting projects can only be done from the Dashboard Service.

  1. Click into ‘Runs’ in the Dashboard.
  2. Click on the project you want to delete from the lefthand sidebar.
  3. On this page, to the far right, click on ‘Settings’.
  4. At the very bottom of the Settings page click the ‘Remove Project’ button.

Delete project dialog

Recorded runs

Recorded runs capture the results from your test runs.

If you haven’t set up your project to record read here.

What is recorded?

Run details

Details of each run are displayed including:

  • The number of skipped, pending, passing, and failing tests.
  • The GitHub branch, pull request, author, commit sha and commit message associated with the run (if any)
  • The times the run, each spec file, and test started and ended.
  • What Continuous Integration the run ran in (if any) and its CI id and url.
  • The operating system and version
  • The browser and version
  • The Cypress version

Spec files

You can see the result of each spec file that ran within Specs. There is also the option to switch between Timeline View and Bar Chart View.

Timeline View

The Timeline View charts your spec files as they ran relative to each other. This is especially helpful when you want to visualize how your tests ran in parallel.

Bar Chart View

The Bar Chart View charts the lengths of each spec file. This view is helpful to determine which spec files or tests are running longer than others.

Jump to failed tests

If you had any failed tests, you can hover over the spec chart and click on the link to the failed test to go directly to its error message and stack trace.

><a href=#Standard-output class=headerlink title= Standard output></a>{% fa fa-code fa-fw Standard output

Standard output includes details and summaries of your tests for each spec file based on the reporter you have set. By default it is the spec reporter.

You will also see a summary at the bottom indicating the screenshots, or videos that were uploaded during the recording.

Screenshots

All screenshots taken during the test run can be found in the Screenshots of the spec. Both screenshots taken during failures and screenshots taken using the cy.screenshot() command will show up here.

Videos

The video recorded during the test run can be found under the Video of the spec. You can also download the video.

Test failures

Any tests that fail during a test run can be found under the Failures tab. Each failure is listed under its test title.

Each failure displays:

  • Test title: The title of the failed test.
  • Error: The stack trace of the error.
  • Screenshot: Any screenshots taken during the test.
  • Video: The recorded video scrubbed to the point of failure in the test.

Organizations

Organizations are used to group projects and manage access to those projects.

Organizations

With organizations you can:

  • Create projects
  • Invite users
  • Transfer projects
  • Pay for all of your projects usage.

Create Org

You can create an organization from within the Dashboard Service by going to the Organizations tab and clicking Add Organization.

Add Organization dialog

Personal Orgs

By default, every user of Cypress is given a personal organization - named after you. You cannot delete or edit the name of this default organization.

Manage users

Inviting users

You can invite users to Cypress from the Dashboard Service. Invited users will see all projects and tests run for the organization.

To invite a user to an organization:

  1. Click into the organization you want the user to access.
  2. Click Users, then Invite User. Note: you must have the role of ‘owner’ or ‘admin’ to invite users.
  3. Fill in their email and select their role then click ‘Invite User’ Note: only ‘owners can give other user’s ‘owner’ access.
  4. The user will receive an invite email with a link to accept the invitation.

Invite User dialog

User roles

Users can be assigned roles that affect their access to certain features of the Dashboard Service.

  • Member: Can see the projects, runs, and keys.
  • Admin: Can also invite, edit and delete users.
  • Owner: Can also transfer or delete projects. Can delete and edit the organization.

User requests

Users can “request” access to a given organization. If a developer on your team has access to Cypress and your project’s source code - they can request to be given access to your organization. This means instead of you having to invite team members up front, they can simply request access and you can choose to accept or deny them access.

Delete Org

You can delete organizations that you own as long as they do not have any projects in the organization. You must first transfer ownership of your projects to another organization before you can delete the organization.

Delete Organization