The URL that appears in the browser's URL bar is one of the first and primary ways that users interact with our web apps. The URL tells the app and the user of their location within the route hierarchy of the app. It sometimes even contains state. The URL consequently serves as an excellent first assertion when writing integration tests.
When writing Cypress integration tests, there are several ways for us to assert about the current URL.
We can assert about the entire URL:
// URL: http://localhost:8000/pokemon cy.url().should('eq', 'http://localhost:8000/pokemon'); // ✅ passes
This is certain the most precise assertion. The tradeoff is that it requires
us to know something about the environment configuration (namely,
baseUrl). This can get verbose and make our tests brittle.
Alternatively, we can make a partial assertion about the URL:
// URL: http://localhost:8000/pokemon cy.url().should('contain', '/pokemon'); // ✅ passes
This frees us from having to specify the full path with the base URL. This, too, has a potential drawback. This way of asserting about the URL can be overly permissive and may result in a false-positive.
Imagine we are writing a test for our pokemon show page. As part of that
test we want to be sure that the back button works. We are on the show
page for a specific pokemon (
/pokemon/2) and our back button is not
correctly wired up yet. Here is our assertion:
// Click: 'Back' -- no change in URL // URL: http://localhost:8000/pokemon/2 cy.url().should('contain', '/pokemon'); // ✅ passes (false positive)
What we'd like is a stricter assertion without the need to specify the base
URL. This is where
cy.location() can help.
// Click: 'Back' -- no change in URL // URL: http://localhost:8000/pokemon/2 cy.location('pathname').should('eq', '/pokemon'); // ❌ fails
This time our assertion correctly fails because
/pokemon does not match
the current pathname of
/pokemon/2. Once we update our application code
with a working back button we should see this test pass. Going forward we
will have the confidence that if the back button breaks again, so will the
We looked at a couple ways to assert about the current state of your app's
cy.url() can certainly be used to this end, I recommend
cy.location(). There is a lot more to
cy.location() than we
covered in this post. Check out the
the Cypress docs for all the other ways this function can be used to assert
about the URL.
Want to see more of the code? Check out the supplementary repository.
Cover photo credit: Jean-Frederic Fortier