Cypress - Build First Test

Cypress - Building Your First Test

Once Cypress is installed and configured in your project, it creates a recommended folder structure. You’ll typically write your test files (e.g., myFirstTest.cy.js) within the cypress/e2e folder for end-to-end tests. The .cy.js (or .cy.ts for TypeScript) extension is the modern convention for Cypress spec files.

Previously, the primary folder for tests was cypress/integration. With Cypress version 10 and later, this has been standardized to cypress/e2e for end-to-end tests and cypress/component for component tests.

Modern Cypress Folder Structure

Let’s understand the typical folder structure in a modern Cypress project:

• cypress/e2e - This is where your end-to-end test files (specs) reside. For example, login.cy.js or todo-app.cy.js.
• cypress/fixtures - Contains static data files (e.g., JSON) that your tests can use. Useful for mocking API responses or providing consistent test data. Example: user.json.
• cypress/support - This folder contains reusable custom commands and global configurations. Key files include:
  • commands.js (or .ts): For creating custom commands (e.g., cy.login()).
  • e2e.js (or .ts): Runs before every single spec file in the e2e directory. Ideal for global beforeEach hooks or importing custom commands.
• cypress/screenshots - Cypress automatically saves screenshots here when tests fail (if configured) or when cy.screenshot() is used.
• cypress/videos - Cypress can record videos of test runs, which are saved here, especially useful for CI environments.
• cypress/downloads - If your tests download files, Cypress will place them in this folder by default.
• node_modules - Contains all project dependencies, including Cypress itself, installed via npm or yarn. This is essential for project execution.
• cypress.config.js (or cypress.config.ts) - This is the main configuration file for Cypress (replacing the older cypress.json). Here you define project-specific settings, environment variables, and configure plugins via setupNodeEvents. This file is mandatory for Cypress 10+.
• package.json - Standard Node.js file that lists project dependencies (including Cypress) and scripts (e.g., for running Cypress tests).

Structure of a Basic Test

Cypress tests are built using a syntax similar to JavaScript testing frameworks like Mocha and Jasmine. Here’s the fundamental structure:

• A test suite is defined using the describe() function, which groups related tests. It takes a string for the suite name and a callback function.
• Individual test cases within a suite are defined using the it() function (or its alias specify()). It takes a string for the test case name and a callback function containing the test steps.
• Test steps, which are Cypress commands (e.g., cy.visit(), cy.get()), are written inside the it() block.

Basic Test Implementation

Here’s an example of a basic test in a file named example.cy.js:

cypress/e2e/example.cy.js

describe('My First Test Suite', function() {
  it('Visits the Kitchen Sink and asserts title', function() {
    // Test Step 1: Visit a URL
    cy.visit('https://example.cypress.io');

    // Test Step 2: Query for an element and make an assertion
    cy.contains('type').click();

    // Test Step 3: Should be on a new URL which includes '/commands/actions'
    cy.url().should('include', '/commands/actions');

    // Test Step 4: Get an input, type into it and verify the value
    cy.get('.action-email')
      .type('fake@email.com')
      .should('have.value', 'fake@email.com');
  });
});

The cy object provides access to all Cypress commands. It’s globally available in your test files, so you don’t need to import or require it.

Test Execution

You can run your Cypress tests in two main ways:

1. Using the Cypress Test Runner (Interactive Mode):

npx cypress open

This command opens the Cypress Test Runner, which provides an interactive interface. You can see your spec files, choose a browser, and watch your tests run in real-time. This is highly recommended for writing and debugging tests.

2. Running Headless (Command Line):

npx cypress run

This command runs all spec files in the cypress/e2e folder (by default) in a headless browser (usually Electron). This is ideal for CI/CD pipelines or when you just want a quick run of all tests. By default, videos and screenshots on failure are often enabled in this mode.

To run a specific spec file from the command line:

npx cypress run --spec "cypress/e2e/myFirstTest.cy.js"

When you execute a specific file, the Test Runner (if opened with cypress open) will focus on that file, or the command line output will detail the results for that specific file. You’ll see logs indicating the progress and outcome (pass/fail) of your test(s).

Common Learning Obstacle: Ensure Node.js and npm (or yarn) are installed, as npx is part of npm. If cypress command is not found, ensure Cypress is listed as a dev dependency in your package.json and installed via npm install cypress --save-dev.

Real-world Application: Writing a simple test to visit your application’s homepage and verify the title or a key heading is a great first step to ensure the basic deployment is working.