Testing Your App

Step 1: Start your server

Assuming you've successfully installed Cypress and opened Cypress in your project, the first thing you'll want to do is start your local development server that hosts the application.

It should look something like http://localhost:8080.

Step 2: Visit your server

Once your server is running, it's time to visit it.

Let's delete the sample.cy.js file created in the previous tutorial now that it's no longer needed.

rm cypress/e2e/sample.cy.js

Now let's create our own spec file called home_page.cy.js.

touch cypress/e2e/home_page.cy.js

Once that file is created, you should see it in the list of spec files.

Now you'll need to add in the following code in your test file to visit your server:

describe('The Home Page', () => {
  it('successfully loads', () => {
    cy.visit('http://localhost:8080') // change URL to match your dev URL
  })
})

Now click on the home_page.cy.js file and watch Cypress open your browser.

If you forgot to start your server you'll see the error below:

If you've started your server, then you should see your application loaded and working.

Step 3: Configure Cypress

If you think ahead, you'll quickly realize that you're going to be typing this URL a lot, since every test is going to need to visit some page of your application. Luckily, Cypress provides a configuration option for this. Let's leverage that now.

Open up your configuration file. It starts out empty, but let's add the baseUrl option.

const { defineConfig } = require('cypress')

module.exports = defineConfig({
  e2e: {
    baseUrl: 'http://localhost:8080'
  }
})

import { defineConfig } from 'cypress'

export default defineConfig({
  e2e: {
    baseUrl: 'http://localhost:8080'
  }
})

{
  "e2e": {
    "baseUrl": "http://localhost:8080"
  }
}

This will automatically prefix cy.visit() and cy.request() commands with this baseUrl.

We can now visit a relative path and omit the hostname and port.

describe('The Home Page', () => {
  it('successfully loads', () => {
    cy.visit('/')
  })
})

Great! Everything should still be green.

Testing strategies

You're about to embark on writing tests for your application, and only you know your application, so we don't have a lot of specific advice to give you.

What to test, where the edge cases and seams are, what regressions you're likely to run into, etc. are entirely up to you, your application, and your team.

That said, modern web testing has a few wrinkles that every team experiences, so here are some quick tips on common situations you're likely to run into.

Seeding data

Depending on how your application is built - it's likely that your web application is going to be affected and controlled by the server.

Typically these days servers communicate with front end apps via JSON, but you could also be running a traditional server-side rendered HTML web application.

Generally the server is responsible for sending responses that reflect some kind of state it holds - generally in a database.

Traditionally when writing e2e tests using Selenium, before you automate the browser you do some kind of set up and tear down on the server.

Perhaps you'll need to generate a user, and seed them with associations and records. You may be familiar with using things such as fixtures or factories.

To test various page states - like an empty view, or a pagination view, you'd need to seed the server so that this state can be tested.

While there is a lot more to this strategy, you generally have three ways to facilitate this with Cypress:

• cy.exec() - to run system commands
• cy.task() - to run code in Node via the setupNodeEvents function
• cy.request() - to make HTTP requests

If you're running node.js on your server, you might add a before or beforeEach hook that executes an npm task.

describe('The Home Page', () => {
  beforeEach(() => {
    // reset and seed the database prior to every test
    cy.exec('npm run db:reset && npm run db:seed')
  })

  it('successfully loads', () => {
    cy.visit('/')
  })
})

Instead of just executing a system command, you may want more flexibility and could expose a series of routes only when running in a test environment.

For instance, you could compose several requests together to tell your server exactly the state you want to create.

describe('The Home Page', () => {
  beforeEach(() => {
    // reset and seed the database prior to every test
    cy.exec('npm run db:reset && npm run db:seed')

    // seed a post in the DB that we control from our tests
    cy.request('POST', '/test/seed/post', {
      title: 'First Post',
      authorId: 1,
      body: '...',
    })

    // seed a user in the DB that we can control from our tests
    cy.request('POST', '/test/seed/user', { name: 'Jane' })
      .its('body')
      .as('currentUser')
  })

  it('successfully loads', () => {
    // this.currentUser will now point to the response
    // body of the cy.request() that we could use
    // to log in or work with in some way

    cy.visit('/')
  })
})

While there's nothing really wrong with this approach, it does add a lot of complexity. You will be battling synchronizing the state between your server and your browser - and you'll always need to set up / tear down this state before tests (which is slow).

The good news is that we aren't Selenium, nor are we a traditional e2e testing tool. That means we're not bound to the same restrictions.

With Cypress, there are several other approaches that can offer an arguably better and faster experience.

Stubbing the server

Another valid approach opposed to seeding and talking to your server is to bypass it altogether.

While you'll still receive all of the regular HTML / JS / CSS assets from your server and you'll continue to cy.visit() it in the same way - you can instead stub the JSON responses coming from it.

This means that instead of resetting the database, or seeding it with the state we want, you can force the server to respond with whatever you want it to. In this way, we not only prevent needing to synchronize the state between the server and browser, but we also prevent mutating state from our tests. That means tests won't build up state that may affect other tests.

Another upside is that this enables you to build out your application without needing the contract of the server to exist. You can build it the way you want the data to be structured, and even test all of the edge cases, without needing a server.

However - there is likely still a balance here where both strategies are valid (and you should likely do them).

While stubbing is great, it means that you don't have the guarantees that these response payloads actually match what the server will send. However, there are still many valid ways to get around this:

Generate the fixture stubs ahead of time

You could have the server generate all of the fixture stubs for you ahead of time. This means their data will reflect what the server will actually send.

Write a single e2e test without stubs, and then stub the rest

Another more balanced approach is to integrate both strategies. You likely want to have a single test that takes a true e2e approach and stubs nothing. It'll use the feature for real - including seeding the database and setting up state.

Once you've established it's working you can then use stubs to test all of the edge cases and additional scenarios. There are no benefits to using real data in the vast majority of cases. We recommend that the vast majority of tests use stub data. They will be orders of magnitude faster, and much less complex.

Logging in

One of the first (and arguably one of the hardest) hurdles you'll have to overcome in testing is logging into your application.

Nothing slows a test suite down like having to log in, but all the good parts of your application most likely require an authenticated user! Here are some tips.

Fully test the login flow -- but only once!

It's a great idea to get your signup and login flow under test coverage since it is very important to all of your users and you never want it to break.

Logging in is one of those features that are mission critical and should likely involve your server. We recommend you test signup and login using your UI as a real user would:

Here's an example alongside seeding your database:

describe('The Login Page', () => {
  beforeEach(() => {
    // reset and seed the database prior to every test
    cy.exec('npm run db:reset && npm run db:seed')

    // seed a user in the DB that we can control from our tests
    // assuming it generates a random password for us
    cy.request('POST', '/test/seed/user', { username: 'jane.lane' })
      .its('body')
      .as('currentUser')
  })

  it('sets auth cookie when logging in via form submission', function () {
    // destructuring assignment of the this.currentUser object
    const { username, password } = this.currentUser

    cy.visit('/login')

    cy.get('input[name=username]').type(username)

    // {enter} causes the form to submit
    cy.get('input[name=password]').type(`${password}{enter}`)

    // we should be redirected to /dashboard
    cy.url().should('include', '/dashboard')

    // our auth cookie should be present
    cy.getCookie('your-session-cookie').should('exist')

    // UI should reflect this user being logged in
    cy.get('h1').should('contain', 'jane.lane')
  })
})

You'll likely also want to test your login UI for:

• Invalid username / password
• Username taken
• Password complexity requirements
• Edge cases like locked / deleted accounts

Each of these likely requires a full blown e2e test.

Reusing the login code

At this point there's nothing stopping you copying and pasting the login code above into every one of your tests that needs an authenticated user. Or you could even put all your tests in one big spec file and put the login code in a beforeEach block. But neither of those approaches is particularly maintainable, and they're certainly not very elegant. A much better solution is to use a cy.login() custom command.

Custom commands allow you to easily encapsulate and reuse Cypress test logic. They're basically just functions, but with some added sugar to allow you to use them with the same chaining API as the built-in Cypress commands. Here's an example of the login code from the previous section converted into a custom command:

// In cypress/support/commands.js

Cypress.Commands.add('login', (username, password) => {
  cy.visit('/login')

  cy.get('input[name=username]').type(username)

  // {enter} causes the form to submit
  cy.get('input[name=password]').type(`${password}{enter}`)

  // we should be redirected to /dashboard
  cy.url().should('include', '/dashboard')

  // our auth cookie should be present
  cy.getCookie('your-session-cookie').should('exist')

  // UI should reflect this user being logged in
  cy.get('h1').should('contain', username)
})

// In your spec file

it('does something on a secured page', function () {
  const { username, password } = this.currentUser
  cy.login(username, password)

  // ...rest of test
})

Improving performance

You're probably wondering what happened to our advice about logging in "only once". The custom command above will work just fine for testing your secured pages, but if you have more than a handful of tests, logging in before every test is going to add a lot of running time to your suite.

Luckily, Cypress provides the cy.session() command, a powerful performance tool that lets you cache user session data and reuse it for multiple tests without going through multiple login flows! Let's modify the cy.login() command from our previous example to use cy.session():

Cypress.Commands.add('login', (username, password) => {
  cy.session(
    username,
    () => {
      cy.visit('/login')
      cy.get('input[name=username]').type(username)
      cy.get('input[name=password]').type(`${password}{enter}`)
      cy.url().should('include', '/dashboard')
      cy.get('h1').should('contain', username)
    },
    {
      validate: () => {
        cy.getCookie('your-session-cookie').should('exist')
      },
    }
  )
})

There's a lot going on here that's out of the scope of this introduction, so for a more in-depth explanation of how cy.session() works, read the API docs.

Get started

Ok, we're done talking. Now dive in and get started testing your app!

From here you may want to explore some more of our guides:

• Tutorial Videos to watch step-by-step tutorial videos
• Cypress API to learn what commands are available as you work
• Introduction to Cypress explains how Cypress really works
• Command Line for running all your tests outside via cypress run
• Continuous Integration for running Cypress in CI
• Cross Browser Testing for optimally running tests in CI across Firefox and Chrome-family browsers
• Cypress Real World App (RWA) for practical demonstrations of Cypress testing practices, configuration, and strategies in a real-world project.