diff --git a/docs/source/guides/getting-started/testing-your-app.md b/docs/source/guides/getting-started/testing-your-app.md index 1e3a4419a5..6a0d34c485 100644 --- a/docs/source/guides/getting-started/testing-your-app.md +++ b/docs/source/guides/getting-started/testing-your-app.md @@ -64,9 +64,9 @@ If you aren't sure about this, you'll need to track down someone on your team wh Once you get your server booted, refresh the Cypress browser and you should see your application's home page in the app preview pane. Congratulations! You've just taken the first step toward a better integration testing experience for your web application. -# Useful Configuration Options +# Configure Cypress to Go With Your Flow -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 anticipates this need and provides a configuration option for it. Let's leverage that immediately. +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 anticipates this need and provides a configuration option for it. Let's leverage that now. Open up `cypress.json`, which you will find in your project root (where you installed Cypress.) It starts out empty: @@ -74,7 +74,7 @@ Open up `cypress.json`, which you will find in your project root (where you inst {} ``` -...we'll add an option to default our URL in all `cy.visit()` commands (make sure you use your URL if it is different!): +...we'll add an option to default our URL in all `cy.visit()` commands (make sure you replace with *your* URL if it is different!): ```js { @@ -82,7 +82,7 @@ Open up `cypress.json`, which you will find in your project root (where you inst } ``` -Got it? Great! Now let's rewrite that test to just use the path we want to visit instead of the entire URL: +Got it? Great! Now let's rewrite the previous test to just use the path we want to visit instead of the entire URL: ```js describe("The Home Page", function() { @@ -92,19 +92,46 @@ describe("The Home Page", function() { }) ``` -Refresh Cypress and have a look to make sure everything is working, then give yourself a pat on the back: that's a lot of typing our future selves won't be doing! +Refresh Cypress and have a look to make sure everything is working, then give yourself a pat on the back: that's a lot of typing your future self won't be doing! {% note info Configuration Options %} -Cypress has many more configuration options you can use to customize its behavior to your app. Things like where your tests live, default timeout periods, environment variables, which reporters to use, etc. Check them out in the {% url "Configuration Appendix" configuration %}! +Cypress has many more configuration options you can use to customize its behavior to your app. Things like where your tests live, default timeout periods, environment variables, which reporter to use, etc. Check them out in the {% url "Configuration Appendix" configuration %}! {% endnote %} # Think Through Your Testing Strategy +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 advise 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 and your team. + +That said, modern web testing has a few wrinkles that every team experiences, so here's some quick tips on common situations you're likely to run into sooner than later. + ## Logging In with Speed and Grace -## Preparing the Back-end Data Store +Nothing slows a test suite like having to log in, but all the good parts of your application most likely require an authenticated user! Here's some tips. -## Ignoring the Back-end with Network Stubbing +### Fully Test the Login Flow, _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. We recommend you test signup and login the way you test most things in Cypress: + +1. `cy.visit()` the page with the login form +2. `cy.get()` the username and password inputs and `.type()` into them +3. `cy.get()` the login form and `.submit()` it +4. make an appropriate assertion about the next page + +You can quickly test your app's behavior like this for a number of scenarios. For the "happy path", you might include signing up before logging in. Next, incorrect usernames and passwords are obvious scenarios to test, and furthermore you might include edge cases like locked or deleted accounts, username or email already exists at signup, etc. Whatever you need assurances about, get it under coverage! + +But don't try to reuse this login test for every other test... + +### Short-Circuit the Login Flow Everywhere Else + +Now that the signup and login flow are covered, we want to avoid them for tests that aren't specifically about them. For this, we can leverage `cy.request()`, which makes a web request _just like the browser, but outside of the browser_. Cypress will send all the appropriate cookies and headers, just like the browser would, but without engaging all of the graphical overhead of the browser. + +This is where your own knowledge of your web app comes in: What does a login request look like for your app? You want to emulate that with `cy.request()` outright, instead of filling out a form and submitting it manually. + +If you need help getting started with this, you could open up the dev tools and see what the form actually submits. Look at it to see what data you need to send, then do it directly. Keeping your tests fast depends on it! + +## Preparing and Cleaning Up Test Data + +## Isolation from the Back-end with Network Stubbing # Get Started!