Running your first Cypress test

Estimated reading: 4 minutes 18 views

Now that you have written your first Cypress test, it’s time to run it and observe how Cypress interacts with your application in real-time. This article will guide you step by step on how to execute your test, interpret the results, and debug if necessary.

1. Open the Cypress Test Runner

Cypress provides a graphical interface called the Cypress Test Runner to run and manage your tests. Follow these steps to open it:

Open your terminal (e.g., Command Prompt, PowerShell, or the integrated terminal in VS Code).
Navigate to your project directory if you aren’t already there:

				
					cd path-to-your-project

3. Launch the Cypress Test Runner using the following command:

				
					npx cypress open

If Cypress is installed correctly, this command will open the Test Runner.
If you encounter any errors, ensure that Cypress is installed as a development dependency by running:

				
					npm install cypress --save-dev

4. Once the Test Runner opens, it will display the folder structure and list all the spec files available in the cypress/integration/ directory.

2. Running the Test

After the Cypress Test Runner opens, follow these steps to run your test:

Locate the test file you created, e.g., firstTest.spec.js.
Click on the test file name in the Test Runner. This will:
- Open a browser controlled by Cypress.
- Execute the test steps defined in your file.
Observe the test execution in real time. You’ll see:
- Each command executed step by step.
- The state of the application at each stage (with time travel features).
- Logs and screenshots for debugging purposes.

3. Understanding the Test Results

The Cypress Test Runner provides detailed feedback for each step of your test. Here’s what you’ll see:

Left Panel:
- A list of test steps, commands, and assertions.
- Steps that passed will be marked with a green checkmark.
- If a step fails, it will be marked with a red cross, and detailed error information will be displayed.
Main Window:
- The browser controlled by Cypress, where you can see the test actions in real-time.
- Visual snapshots of the application state for each command.
Debugging Tools:
- Click on any test step in the left panel to see the DOM snapshot for that step.
- Use Cypress’s powerful logs to identify issues and understand failures.

4. Running Tests in Headless Mode (Optional)

If you prefer to run your tests without opening the Test Runner (e.g., for CI/CD pipelines), you can execute them in headless mode:

Run the following command:

				
					npx cypress run

2. This will:

- Execute all test files in the cypress/integration/ directory.
- Run tests in the default browser (usually Electron).
- Provide a summary of the results in the terminal.

3. If you want to specify a particular browser (e.g., Chrome), use:

				
					npx cypress run --browser chrome

4. Cypress will save screenshots and videos of test runs (configurable in cypress.json).

5. Debugging Failed Tests

If a test fails, Cypress provides extensive debugging capabilities:

Error Messages:
- Cypress displays detailed error messages explaining why a test failed.
- Use these messages to identify and fix the issue in your code or test.
Time Travel:
- Click on a failed step in the Test Runner to see the state of the application at that moment.
Console Logs:
- Use cy.log() in your test to print custom debug information in the Test Runner.
Screenshots and Videos:
- By default, Cypress saves screenshots of failures and records videos of test runs (if configured).

Conclusion

Running your first Cypress test is an important step in understanding how Cypress operates. The Test Runner provides a user-friendly and powerful interface for executing tests, observing their behavior, and debugging issues. Whether you run tests interactively or in headless mode, Cypress ensures a seamless testing experience.

In the next articles, we will explore more advanced testing scenarios, handling dynamic content, and optimizing test performance for large test suites.