How to run Cypress tests from the command line

To get started with Cypress for command line execution, the first step is ensuring you have Node.js installed on your machine. Cypress runs on Node, so if you haven’t already, go ahead and download it from the official Node.js website. Once Node.js is installed, you can easily set up Cypress using npm.

Open your terminal and navigate to your project directory. Run the following command to install Cypress:

npm install cypress --save-dev

This will add Cypress as a development dependency in your project. Once the installation completes, you can open Cypress using:

npx cypress open

This command starts the Cypress Test Runner, allowing you to run tests interactively. However, since you’re interested in command line execution, you can execute tests directly through the command line using:

npx cypress run

This will run all your tests in the headless mode, which is perfect for continuous integration environments. If you want to run tests in a specific browser, you can specify the browser name like this:

npx cypress run --browser chrome

In addition to running tests in different browsers, you can also control the configuration by passing options. For instance, if you want to run tests in a specific environment, you can set environment variables like so:

npx cypress run --env ENV=staging

By default, Cypress looks for your test files in the cypress/integration folder. If you have tests located in a different directory, you can specify the path using:

npx cypress run --spec "cypress/tests/**/*.spec.js"

This flexibility allows you to structure your tests in a way that makes sense for your project. Another useful command is:

npx cypress run --record --key YOUR_RECORD_KEY

This command records your test run on the Cypress Dashboard, providing you with insights into your test performance. It’s particularly useful for team projects where visibility into test results is crucial. If you’re working in a CI/CD pipeline, incorporating this command can help you track failures and successes over time.

Make sure to check the Cypress documentation for additional configuration options and advanced use cases. For example, you might want to customize the test runner’s behavior or the video recording settings. Knowing how to tailor these settings can significantly enhance your testing process, ensuring that you get the most out of Cypress.

When you start to run your tests, especially in CI, you might want to include flags that improve performance. For instance, running tests with a specific configuration can save time and resources. Keep an eye on the output logs as they provide valuable insights into the test execution process.

npx cypress run --headed --no-sandbox

This command can help you debug tests that fail when running in headless mode. Debugging in a visual context often reveals issues that might not be apparent in headless execution. The key to mastering Cypress in the command line is understanding the various options available and knowing when to use them.

As you dive deeper, remember that the command line interface is your friend. It’s fast, efficient, and integrates seamlessly with most CI tools. The more you leverage it, the smoother your testing workflow will become. You’ll find that running tests from the command line not only speeds up your feedback loop but also integrates well into your development cycle.

Understanding Cypress commands and options

Cypress commands are powerful tools that give you control over your testing environment. Understanding these commands and their options can significantly enhance your testing strategy. For example, you can set the number of retries for failed tests, which is particularly useful in flaky tests that may fail intermittently.

npx cypress run --retries 2

This command will allow each test to retry twice before marking it as failed. It’s a useful feature when you’re dealing with network requests or other asynchronous operations that may not always succeed on the first try.

Moreover, you can customize the timeout settings to ensure that your tests don’t hang indefinitely. The default timeout for commands is 4 seconds, but you can adjust it to fit your needs:

npx cypress run --config defaultCommandTimeout=10000

This sets the default command timeout to 10 seconds, which can be helpful when working with slower applications or complex interactions. It’s important to balance timeouts to avoid unnecessarily long waits while still ensuring your tests are robust.

Another option worth mentioning is the ability to run tests with different configurations for various environments. You can set configurations directly in the command line. For example, if you want to use a different base URL for your tests, you could do the following:

npx cypress run --config baseUrl=https://staging.example.com

This allows you to switch environments without modifying your test files. Keeping your test configurations flexible is crucial for maintaining a clean and manageable codebase.

Additionally, Cypress supports parallel test execution, which can dramatically reduce the time it takes to run your test suite. To enable parallelization, you can use the following command:

npx cypress run --parallel

This command requires that you have set up your project to record the results on the Cypress Dashboard. Parallelization is especially beneficial for large test suites, as it distributes the tests across multiple machines or processes.

When running tests in parallel, it’s important to ensure that your tests are independent and do not rely on shared state. This is where modularizing your tests and using fixtures can come in handy. Structuring your tests to avoid side effects will lead to more reliable outcomes.

As you continue to work with Cypress, don’t overlook the importance of logging and reporting. You can enhance your command line execution by enabling detailed logs. This can be done with:

npx cypress run --reporter spec

The spec reporter will give you a detailed output of the test results directly in the terminal, which is useful for quick reviews and debugging. There are various reporters available, so you can choose based on your project requirements.

Moreover, if you want to save the results in a specific format, you can specify the reporter options accordingly. For instance, to generate a JSON report, you might run:

npx cypress run --reporter json --reporter-options "output=results.json"

This command will create a JSON file containing the results of your test run, which can be useful for further analysis or integration with other tools in your development pipeline.

Lastly, always remember to keep your Cypress version updated. New releases often come with performance improvements, bug fixes, and new features that can enhance your testing experience. Keeping an eye on the release notes will help you stay informed about what’s new and how you can leverage the latest capabilities in your projects.

In summary, understanding the various commands and options available in Cypress will empower you to run your tests more effectively. The command line interface is not just a tool; it’s a gateway to optimizing your testing workflow, and mastering it can lead to smoother development cycles and improved product quality. As you experiment with different configurations and options, you’ll discover the nuances that suit your particular testing needs, leading to a more robust testing strategy.

Always strive to keep your testing environment clean, maintainable, and adaptable to changes. This mindset will help you as you navigate the complexities of testing modern web applications with Cypress.

Best practices for running tests efficiently

Running tests efficiently is not just about making them go faster; it’s about getting feedback quicker so you can iterate more effectively. One of the most significant ways to reduce the total runtime of your test suite is by running tests in parallel. If your test suite takes 30 minutes to run, splitting it across three parallel machines in your CI environment can bring that time down to around 10 minutes. The Cypress Dashboard handles the load balancing for you. All you need to do is configure your CI provider to spin up multiple containers and add the --parallel flag to your run command.

npx cypress run --record --key YOUR_KEY --parallel

For parallelization to work correctly, your tests must be atomic. This is non-negotiable. One test cannot depend on the state created by another. If Test A creates a user and Test B expects that user to exist, they will fail when run in parallel because there’s no guarantee Test A runs first. Each test should be responsible for setting up its own state and, if necessary, cleaning up after itself. The beforeEach hook is your best friend for this. Use it to programmatically set up whatever conditions your test needs to run reliably.

beforeEach(() => {
  // Use a custom command to reset the database and seed necessary data
  cy.task('db:seed', { user: 'test-user.json' });
  // Programmatically log in instead of using the UI
  cy.login('test-user', 'password123');
});

While parallelization is great for CI, it’s overkill for local development. When you’re working on a specific feature, you don’t want to run the entire test suite. You want to run only the tests relevant to the code you’re changing. The --spec flag lets you do exactly that. By pointing Cypress to a single test file, you can get feedback in seconds instead of minutes.

npx cypress run --spec "cypress/integration/features/shopping-cart.spec.js"

Another huge efficiency gain comes from controlling your application’s network requests. Your end-to-end tests are primarily for verifying UI behavior, not for testing your backend API. Waiting for real network responses slows down your tests and makes them flaky. Use cy.intercept() to stub network requests. This command allows you to catch outgoing requests from your application and provide a predefined response instantly, isolating your frontend from any backend issues or latency.

it('should display products after fetching them', () => {
  // Intercept the API call and return a canned response from a fixture file
  cy.intercept('GET', '/api/products', { fixture: 'products.json' }).as('getProducts');

  cy.visit('/products');
  cy.wait('@getProducts'); // Wait for the stubbed response, not a real one

  cy.get('.product-item').should('have.length', 5); // Assert against the fixture data
});

This approach makes your tests lightning-fast and 100% reliable. The backend can be down for maintenance, but your frontend tests will continue to pass because they no longer depend on it. You’re testing your application’s behavior in a controlled environment.

Cypress also generates videos and screenshots, which are invaluable for debugging failures in CI. However, this process consumes resources and adds time to your test runs. For local development or for runs where you only care about a pass/fail status, you can disable them to speed things up. You can easily toggle these settings from the command line.

npx cypress run --config video=false,screenshotOnRunFailure=false

Finally, optimize common actions like logging in. Instead of using the UI to fill out a login form in every test that requires an authenticated user, create a custom command that logs in programmatically. This usually involves using cy.request() to send credentials directly to your authentication endpoint and then setting the session token or cookie manually. This bypasses the UI entirely, saving a significant amount of time across your entire test suite.

// In cypress/support/commands.js
Cypress.Commands.add('loginByApi', (email, password) => {
  cy.request('POST', '/api/auth/login', { email, password }).then((response) => {
    // Assuming the API returns a token that you can set in local storage
    window.localStorage.setItem('auth-token', response.body.token);
  });
});

By combining these strategies-parallel execution in CI, targeted test runs locally, network stubbing, and programmatic shortcuts for common actions-you can create a highly efficient testing workflow that provides fast, reliable feedback.