Learn Cypress - Installation & Basic Configuration

#Introduction

The first two episodes covered concepts and architecture. Now it's time to get hands-on. Episode 3 walks you through installing Cypress, opening the Test Runner, writing your first test, and putting together the basic configuration you will use throughout the series.

By the end of this episode, you will have a living Cypress project: you can open the Test Runner, watch tests run in real time, and execute them from the command line.

#Installing Cypress and Setting Up the Project

Enter the project directory you created in episode 0, then install Cypress:

npm install cypress --save-dev

npm install cypress --save-dev adds Cypress to your devDependencies. This process also downloads the Cypress binary to your local cache — on the first install, this can take a few minutes.

When it finishes, verify that the binary is installed:

npx cypress verify

npx cypress verify makes sure the Cypress binary is compatible with your system. If you see errors about missing system libraries on Linux, install the required dependencies and run it again.

#Opening the Cypress UI and Writing the First Test

Open the Test Runner for the first time:

npx cypress open

On first launch, Cypress creates the cypress folder and example spec files. Click E2E Testing, choose a browser, then click an example spec to watch the first test run.

Now write your first spec. Replace the contents of cypress/e2e/example.cy.js or create a new file:

First spec

describe("First test", () => {
  it("loads the example page", () => {
    cy.visit("https://example.com");
    cy.contains("Example Domain").should("be.visible");
  });
});

cy.visit("https://example.com") opens the page, then cy.contains("Example Domain") looks for the text and .should("be.visible") makes sure the element is visible. Save the file, and the Test Runner automatically runs it again — this is the real-time reload we discussed in episode 1.

#Configuring cypress.config.js

#Setting baseUrl and Viewport

So tests don't have to write the full URL every time, set baseUrl. Also configure the default viewport:

Full e2e configuration

const { defineConfig } = require("cypress");
 
module.exports = defineConfig({
  e2e: {
    baseUrl: "http://localhost:3000",
    viewportWidth: 1280,
    viewportHeight: 720,
    defaultCommandTimeout: 10000,
    retries: 2,
  },
});

With baseUrl, cy.visit("/") automatically goes to http://localhost:3000. The viewportWidth and viewportHeight properties simulate the screen size.

#Timeout and Retries

defaultCommandTimeout sets the wait limit for commands — here 10000 milliseconds, more generous than the default of 4000. Meanwhile, retries controls how often failed tests are re-attempted at the suite level; we will dissect both deeper in episodes 5 and 13.

CYPRESS_BASE_URL=http://localhost:3000
CYPRESS_DEFAULT_COMMAND_TIMEOUT=10000

Every configuration option can be overridden through environment variables prefixed with CYPRESS_. The CYPRESS_BASE_URL approach is useful when running tests in different environments, such as staging versus production.

#Adding a Test Script to package.json

So your team can run tests easily, add scripts to package.json:

{
  "scripts": {
    "test": "cypress run",
    "test:open": "cypress open",
    "test:headless": "cypress run --browser chrome"
  }
}

• npm run test runs the entire suite in headless mode — without a UI.
• npm run test:open opens the interactive Test Runner.
• npm run test:headless runs the suite in the Chrome browser.

To run, use npm run test:open and pick the spec you want to watch.

#Closing

Episode 3 completed the setup: Cypress is installed as a dev dependency, the Test Runner is open with your first spec running in real time, cypress.config.js configures baseUrl, viewport, timeout, and retries, and the npm run test script is available for headless suite runs.

The key takeaways:

• npm install cypress --save-dev then npx cypress verify to make sure the binary is ready.
• npx cypress open opens the Test Runner; save the file and the test reruns automatically.
• baseUrl, viewport, and defaultCommandTimeout are set in cypress.config.js.
• Configuration options can be overridden through CYPRESS_ env vars.
• Add the test and test:open scripts to package.json.

In the next episode, episode 4, we will cover writing basic Cypress tests — using cy.visit(), cy.get(), basic actions like clicks and typing, assertions with .should() and .contains(), navigation, forms, and debugging techniques directly in the browser. Your first tests will start to feel like a real tool.