End-to-End Testing: Your First Test with Cypress | Cypress Documentation (2024)

Add a test file​

Assuming you've successfullyinstalled Cypress andopened Cypress, now it's time to addyour first test. We're going to do this with the Create new emptyspec button.

On clicking it, you should see a dialog where you can enter the name of your newspec. Just accept the default name for now.

The newly-generated spec is displayed in a confirmation dialog. Just go aheadand close it with the ✕ button.

Once we've created that file, you should see it immediately displayed in thelist of end-to-end specs. Cypress monitors your spec files for any changes andautomatically displays any changes.

Even though we haven't written any code yet - that's okay - let's click on yournew spec and watch Cypress launch it. Spoiler alert: it's probably going toFAIL. Don't worry, it's just because you haven't set up Cypress to visit apage in your app yet! Let's try something different.

Write your first test​

Now it's time to write your first test. We're going to:

1. Write your first passing test.
2. Update it so it fails.
3. Watch Cypress reload in real time.

Open up your favorite IDE and replace the contents of your spec with the codebelow.

describe('My First Test', () => {
 it('Does not do much!', () => {
 expect(true).to.equal(true)
 })
})

Once you save this change you should see the browser reload.

Although it doesn't do anything useful, this is our first passing test! ✅

Over in the Command Log you'llsee Cypress display the suite, the test and your first assertion (which shouldbe passing in green).

Now let's write our first failing test.

describe('My First Test', () => {
 it('Does not do much!', () => {
 expect(true).to.equal(false)
 })
})

Once you save again, you'll see Cypress display the failing test in red sincetrue does not equal false.

Cypress also displays the stack trace and the code frame where the assertionfailed (when available). You can click on the blue file link to open the filewhere the error occurred inyour preferred file opener.To read more about the error's display, read aboutDebugging Errors.

Cypress gives you a visual structure ofsuites, tests, and assertions. Soon you'll also see commands, page events,network requests, and more.

Write a real test​

A solid test generally covers 3 phases:

1. Set up the application state.
2. Take an action.
3. Make an assertion about the resulting application state.

You might also see this phrased as "Given, When, Then", or "Arrange, Act,Assert". But the idea is: First you put the application into a specific state,then you take some action in the application that causes it to change, andfinally you check the resulting application state.

Today, we'll take a narrow view of these steps and map them cleanly to Cypresscommands:

1. Visit a web page.
2. Query for an element.
3. Interact with that element.
4. Assert about the content on the page.

Step 1: Visit a page​

First, let's visit a web page. We will visit ourKitchen Sink application in this exampleso that you can try Cypress out without needing to worry about finding a page totest.

We can pass the URL we want to visit to cy.visit().Let's replace our previous test with the one below that actually visits a page:

describe('My First Test', () => {
 it('Visits the Kitchen Sink', () => {
 cy.visit('https://example.cypress.io')
 })
})

Save the file and switch back over to the Cypress Test Runner. You might noticea few things:

1. The Command Log now showsthe new VISIT action.
2. The Kitchen Sink application has been loaded into theApp Preview pane.
3. The test is green, even though we made no assertions.
4. The VISIT displays a blue pending state until the page finishesloading.

Had this request come back with a non 2xx status code such as 404 or 500,or if there was a JavaScript error in the application's code, the test wouldhave failed.

Step 2: Query for an element​

Now that we've got a page loaded, we need to take some action on it. Why don'twe click a link on the page? Sounds easy enough, let's go look for one welike... how about type?

To find this element by its contents, we'll usecy.contains().

Let's add it to our test and see what happens:

describe('My First Test', () => {
 it('finds the content "type"', () => {
 cy.visit('https://example.cypress.io')

 cy.contains('type')
 })
})

Our test should now display CONTAINS in theCommand Log and still be green.

Even without adding an assertion, we know that everything is okay! This isbecause many of Cypress' commands are built to fail if they don't find whatthey're expecting to find. This is known as anImplicit Assertion.

To verify this, replace type with something not on the page, like hype.You'll notice the test goes red, but only after about 4 seconds!

Can you see what Cypress is doing under the hood? It's automatically waiting andretrying because it expects the content to eventually be found in the DOM.It doesn't immediately fail!

Before we add another command - let's get this test back to passing. Replacehype with type.

Step 3: Click an element​

Ok, now we want to click on the link we found. How do we do that? Add a.click() command to the end of the previous command, likeso:

describe('My First Test', () => {
 it('clicks the link "type"', () => {
 cy.visit('https://example.cypress.io')

 cy.contains('type').click()
 })
})

You can almost read it like a little story! Cypress calls this "chaining" and wechain together commands to build tests that really express what the app does ina declarative way.

Also note that the App Previewpane has updated further after the click, following the link and showing thedestination page:

Now we can assert something about this new page!

Step 4: Make an assertion​

Let's make an assertion about something on the new page we clicked into. Perhapswe'd like to make sure the new URL is the expected URL. We can do that bylooking up the URL and chaining an assertion to it with.should().

Here's what that looks like:

describe('My First Test', () => {
 it('clicking "type" navigates to a new url', () => {
 cy.visit('https://example.cypress.io')

 cy.contains('type').click()

 // Should be on a new URL which
 // includes '/commands/actions'
 cy.url().should('include', '/commands/actions')
 })
})

Adding more commands and assertions​

We are not limited to a single interaction and assertion in a given test. Infact, many interactions in an application may require multiple steps and arelikely to change your application state in more than one way.

We can continue the interactions and assertions in this test by adding anotherchain to interact with and verify the behavior of elements on this new page.

We can use cy.get() to select an element based on itsclass. Then we can use the .type() command to enter textinto the selected input. Finally, we can verify that the value of the inputreflects the text that was typed with another .should().

In general, the structure of your test should flow query -> query -> command orassertion(s). It's best practice not to chain anything after an action command;for more details on why this is, see our guide onretry-ability.

describe('My First Test', () => {
 it('Gets, types and asserts', () => {
 cy.visit('https://example.cypress.io')

 cy.contains('type').click()

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

 // Get an input, type into it
 cy.get('.action-email').type('[emailprotected]')

 // Verify that the value has been updated
 cy.get('.action-email').should('have.value', '[emailprotected]')
 })
})

And there you have it: a short test in Cypress that visits a page, finds andclicks a link, verifies the URL and then verifies the behavior of an element onthe new page. If we read it out loud, it might sound like:

Or in the Given, When, Then syntax:

And hey, this is a very clean test! We didn't have to say anything about howthings work, just that we'd like to verify a particular series of events andoutcomes.

Record Tests with Cypress Studio​

If you want a minimal code approach to creating tests, you can useCypress Studio to record your browserinteractions and generate tests. Visit ourguide for more information.

Next steps​

• Take our freeTesting your first applicationcourse.
• Learn more about the Cypress App UI.
• Start testing your app.
• Set upintelligent code completionfor Cypress commands and assertions.
• Record your test results to Cypress Cloud foradvanced features like parallelization, flake detection, and more.
• Check out the Real World App (RWA) forpractical demonstrations of Cypress testing practices, configuration, andstrategies in a real-world project.
• Search Cypress's documentation to quickly find what you need.