How to open Cypress test runner UI

Getting Cypress up and running is surprisingly simpler, but there are a few key details that smooth out the process. First, you want to make sure your project has Node.js installed. Cypress depends on Node, so if you haven’t got that set up yet, pause and get that working first.

Once Node is ready, the next step is to add Cypress as a dev dependency. This keeps your testing tools separate from your production code and makes your project easier to maintain. Run:

npm install cypress --save-dev

That pulls down the full Cypress package. The install can be a bit large compared to typical npm modules because it bundles a full browser and Electron runtime. Don’t worry, this is intentional – it keeps your tests running consistently across environments.

With Cypress installed, it’s time to initialize the test folder structure. You can do this by opening Cypress for the first time through npm scripts or directly through the binary. The easiest way is:

npx cypress open

This command launches the Cypress Test Runner UI and automatically creates the cypress/ directory with basic folder structure inside your project. You’ll see directories like integration, fixtures, and support. Integration is where your test specs live, fixtures hold test data, and support is for reusable helpers.

Don’t overlook the generated example tests. They are not just for show – going through them quickly reveals Cypress’ core capabilities and syntax. Once you’re comfortable, you can delete or move them to focus on your own tests.

One subtlety is the cypress.json config file. It’s created automatically with sensible defaults, but you’ll want to tweak this as your test suite grows. For example, setting the base URL of your app to avoid repeating full URLs in every test makes your specs cleaner:

{
  "baseUrl": "http://localhost:3000"
}

This way, cy.visit('/') knows exactly where to go without the clutter. You can also configure timeouts, viewport sizes, and environment variables right here. It’s your central place for controlling Cypress’ behavior.

One last thing before writing your first test: make sure your application is running locally or accessible if you’re hitting a remote server. Cypress doesn’t start your app for you; it just talks to it. So, if your app is on port 3000, ensure it’s live before running tests. Otherwise, you’ll get connection errors that look like test failures but aren’t.

After that, you’re set to write your first spec. Start simple: check if the homepage loads, verify a button is visible, or confirm a text string appears. The syntax is intuitive, chaining commands with cy. prefixes and assertions using .should() for clarity and power:

describe('Homepage', () => {
  it('displays the welcome message', () => {
    cy.visit('/')
    cy.get('h1').should('contain', 'Welcome')
  })
})

Keep your tests small and focused. Cypress retries commands automatically, so if your UI takes a moment to update, it waits patiently rather than immediately failing. This built-in resilience reduces flaky tests dramatically, which is a huge win.

Setting up Cypress right means less time battling configuration and more time writing meaningful tests that catch real bugs. Once your project’s wired up, running tests and iterating on them is a breeze. Next, running the test runner from the command line opens up a whole other level of automation and integration possibilities, especially in CI environments. But for now, just getting this baseline solid is the key to making your automated testing reliable and painless.

Running the test runner from the command line

To run your tests from the command line, you don’t need to rely on the UI. This can be particularly useful for automation or continuous integration workflows. You can run the Cypress test runner headlessly, which means it will execute tests without opening the GUI, making it faster and more suitable for CI environments.

The command to run Cypress tests in headless mode is:

npx cypress run

This command will execute all your tests located in the cypress/integration directory. By default, Cypress runs tests in the Electron browser. If you want to specify a different browser, such as Chrome or Firefox, you can add the --browser flag:

npx cypress run --browser chrome

There are additional flags you can use to customize the test run. For instance, you can specify a particular spec file to run instead of executing all tests. That is handy for debugging specific tests:

npx cypress run --spec cypress/integration/my_test_spec.js

When you run tests from the command line, Cypress provides a summary of the results directly in your terminal. You’ll see how many tests passed, how many failed, and detailed logs for any failures, including screenshots and videos if you have those features enabled.

To enable video recording of your tests, you can modify the cypress.json configuration file:

{
  "video": true
}

This will record a video of the test run, which is invaluable for debugging failed tests later. You can view these videos in the cypress/videos directory after the tests complete.

Another useful aspect of running tests from the command line is the ability to watch for file changes and automatically rerun tests. That’s achieved with:

npx cypress open --watch

However, using this command opens the Cypress Test Runner UI again. For pure command line usage, think integrating it into your build process. This way, you can run tests as part of your deployment pipeline, ensuring that new changes don’t break existing functionality.

By integrating Cypress into your CI/CD pipeline, you can run tests on every commit or pull request. Most CI services like CircleCI, GitHub Actions, or Travis CI have simpler ways to incorporate Cypress commands into their workflows. For example, in GitHub Actions, your configuration might look like this:

jobs:
  cypress:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v2
      - name: Install Node.js
        uses: actions/setup-node@v2
        with:
          node-version: '14'
      - name: Install dependencies
        run: npm install
      - name: Run Cypress tests
        run: npx cypress run

This setup ensures that every time you push code, Cypress runs your tests, giving you immediate feedback on the state of your application. It’s a powerful way to maintain code quality and catch issues early in the development cycle.

As you become more comfortable with Cypress, think exploring custom commands and plugins to extend its functionality. This can help tailor Cypress to your specific testing needs and improve your testing efficiency. For instance, creating custom commands can abstract repetitive tasks and make your tests cleaner:

Cypress.Commands.add('login', (email, password) => {
  cy.visit('/login')
  cy.get('input[name=email]').type(email)
  cy.get('input[name=password]').type(password)
  cy.get('button[type=submit]').click()
})

Now, instead of repeating the login steps in every test, you can simply call cy.login('[email protected]', 'password'). This not only reduces redundancy but also enhances readability. The more you leverage Cypress’ capabilities, the more efficient your testing process becomes, allowing you to focus on what really matters: building great software.

Understanding the test runner interface and controls

The Cypress Test Runner interface is designed to be intuitive, offering a clear view of your tests as they run. When you launch the runner, you’ll see a list of all your test specs in the left sidebar. Clicking on any spec file starts the test execution for that file, providing immediate feedback on the results.

As your tests run, the main panel displays the test output, showing which tests passed and which failed. Each test is represented with a clear label and visual indicators for status. If a test fails, Cypress highlights the failing command, making it simple to identify where things went wrong.

Within the interface, you can also inspect elements directly. This allows you to see the state of the DOM at any moment during the test execution. If a test fails, you can pause the execution and interact with the application manually – a feature that’s invaluable for debugging.

On the right side of the runner, you’ll find the command log. This log provides a detailed history of every command executed during the test, complete with snapshots of the application at each step. Clicking on any command in the log reveals additional information, such as the state of the DOM and any associated errors.

Another useful feature is the ability to take snapshots during test execution. As each command runs, Cypress captures a screenshot that you can reference later. That’s particularly helpful for visual regression testing, where you want to ensure that UI elements haven’t changed unexpectedly.

You can configure the Test Runner to automatically take snapshots on failure by modifying the cypress.json file:

{
  "screenshotOnRunFailure": true
}

This way, when a test fails, you’ll have a visual record of what the application looked like at the time of failure, which can significantly speed up the debugging process.

The Test Runner also supports various controls that enhance your testing experience. You can pause tests, step through commands, or even restart the entire test suite. This flexibility allows you to interactively debug tests, which is a huge advantage when working with complex applications.

One particularly powerful aspect of the interface is the ability to modify the viewport size. This is important for testing responsive designs. You can easily toggle between different screen sizes to see how your application behaves under various conditions. Use the dropdown in the Test Runner to set common viewport sizes or define custom ones:

Cypress.config('viewportWidth', 1280)
Cypress.config('viewportHeight', 720)

Additionally, the Test Runner supports network stubbing and spying, so that you can control the responses your application receives. That’s essential for testing edge cases or ensuring that your application behaves correctly under different network conditions. You can stub a request like this:

cy.intercept('GET', '/api/data', { fixture: 'data.json' }).as('getData')

This command intercepts a GET request to the specified URL and returns a fixture file instead. It allows you to test how your application handles data without relying on a live server.

As you familiarize yourself with the Test Runner, you’ll discover that its controls and features are designed not only to help you execute tests but also to enhance your debugging workflow. The more you leverage these tools, the more efficient and effective your testing process will become.