docs: read through / fixed issues with FAQ

This commit is contained in:
Jennifer Shehane
2017-06-16 11:41:43 -04:00
parent a4dbbc5ad1
commit 81d1cc5fda
6 changed files with 63 additions and 52 deletions
+2 -2
View File
@@ -7,8 +7,8 @@ containerClass: faq
## {% fa fa-angle-right %} Whos behind Cypress?
You can read more about who's behind Cypress on our {% url "here" https://www.cypress.io/about %}.
You can read more about who's behind Cypress on our website {% url "here" https://www.cypress.io/about %}.
## {% fa fa-angle-right %} Are you hiring?
You can check our open positions {% url "here" https://www.cypress.io/jobs %}.
Yes! You can check our open positions and apply {% url "here" https://www.cypress.io/jobs %}.
+10 -10
View File
@@ -9,7 +9,7 @@ containerClass: faq
![Dashboard Screenshot](https://cloud.githubusercontent.com/assets/1271364/22800284/d4dbe1d8-eed6-11e6-87ce-32474ea1000c.png)
The {% url 'Dashboard' https://on.cypress.io/dashboard %} is a Cypress service that gives you access to tests you've recorded - typically when running Cypress tests from your CI provider. The Dashboard provides you insight into what happened during your run.
The {% url 'Dashboard' https://on.cypress.io/dashboard %} is a Cypress service that gives you access to tests you've recorded - typically when running Cypress tests from your {% url "CI provider" continuous-integration %}. The Dashboard provides you insight into what happened during your tests run.
You can read more {% url 'here' dashboard-features %}.
@@ -18,7 +18,7 @@ You can read more {% url 'here' dashboard-features %}.
1. First {% url 'setup the project to record' dashboard-projects#Set-up-a-Project-to-Record %}.
2. Then {% url 'record your runs' dashboard-runs %}.
After recording your tests, you will see them in the Dashboard and in the Desktop Application.
After recording your tests, you will see them in the {% url 'Dashboard' https://on.cypress.io/dashboard %} and in the "Runs" tab of the Desktop Application.
## {% fa fa-angle-right %} How much does it cost?
@@ -32,15 +32,15 @@ We will offer similar pricing models of other Developer Tools you are familiar w
## {% fa fa-angle-right %} How is this different than CI?
Cypress is **complimentary** to your CI provider, and plays a completely different role.
Cypress is **complimentary** to your {% url "CI provider" continuous-integration %}, and plays a completely different role.
It doesn't replace nor change anything related to CI. You will simply run Cypress tests in your CI provider.
It doesn't replace or change anything related to CI. You will simply run Cypress tests in your CI provider.
The difference is that your CI provider has no idea what is going on inside of the Cypress process. It's simply programmed to know whether or not a process failed - based on whether it had an exit code greater than `0`.
The difference between our {% url 'Dashboard' dashboard-features %} and your CI provider is that your CI provider has no idea what is going on inside of the Cypress process. It's simply programmed to know whether or not a process failed - based on whether it had an exit code greater than `0`.
Our dashboard provides you with the low level details of *what* happened during your run. Using both your CI provider + Cypress together gives the insight required to debug your test runs.
Our {% url 'Dashboard' dashboard-features %} provides you with the low level details of *what* happened during your run. Using both your CI provider + Cypress together gives the insight required to debug your test runs.
When a run happens and a test fails - instead of going and inspecting your CI provider's `stdout` output, you can log into the {% url 'Dashboard' https://on.cypress.io/dashboard %} and see all of the test run results. It should be instantly clear what the problem was.
When a run happens and a test fails - instead of going and inspecting your CI provider's `stdout` output, you can log into the {% url 'Dashboard' https://on.cypress.io/dashboard %}, see the `stdout` as well as screenshots and video of the tests running. It should be instantly clear what the problem was.
## {% fa fa-angle-right %} Can I host the Dashboard data myself?
@@ -50,15 +50,15 @@ No, although we are looking to build an on-premise version of the Dashboard for
Of course. The dashboard is a separate service from the Desktop Application and will always remain optional. We hope you'll find a tremendous amount of value out of it, but it is not coupled to being able to run your tests.
You can simply always run your tests in CI using {% url '`cypress run`' cli-tool#cypress-run %} without the `--record` flag which does not communicate with our external servers and will not record any test results.
You can simply always run your tests in CI using {% url "`cypress run`" cli-tool#cypress-run %} without the `--record` flag which does not communicate with our external servers and will not record any test results.
## {% fa fa-angle-right %} What is the difference between public and private projects?
**A public project** means that anyone can see the recorded runs for it. It's similar to how public projects on Github, Travis, or Circle are handled. Anyone who knows your `projectId` will be able to see the recorded runs for public projects.
**A public project** means that anyone can see the recorded runs for it. It's similar to how public projects on Github, Travis, or Circle are handled. Anyone who knows your `projectId` will be able to see the recorded runs, screenshots, and videos for public projects.
**A private project** means that only {% url 'users' dashboard-organizations#Inviting-Users %} you explicitly invite to your {% url 'organization' dashboard-organizations %} can see its recorded runs. Even if someone knows your `projectId`, they will not have access to your runs unless you have invited them.
A Record Key has nothing to do with *viewing* build data - it's a "write only" key. Even if it is accidentally leaked, it will not affect who can "see" your builds.
The Record Key has nothing to do with *viewing* build data - it's a "write only" key. Even if it is accidentally leaked, it will not affect who can "see" your builds.
## {% fa fa-angle-right %} What does Cypress record?
+13 -12
View File
@@ -16,11 +16,11 @@ Cypress is kind of a hybrid application/framework/service all rolled into one. I
**Mocha**
Mocha is a testing framework for JavaScript. {%url "Mocha" http://mochajs.org/%} gives you the `it`, `describe`, `beforeEach` methods. Cypress isn't **different** from Mocha, it actually **uses** Mocha under the hood. All of your tests will be written on top of Mocha's `bdd` interface.
Mocha is a testing framework for JavaScript. { %url "Mocha" http://mochajs.org/ %} gives you the `it`, `describe`, `beforeEach` methods. Cypress isn't **different** from Mocha, it actually **uses** Mocha under the hood. All of your tests will be written on top of Mocha's `bdd` interface.
**Karma**
A unit testing runner for JavaScript, {% url "Karma" http://karma-runner.github.io/ %}, works with either `Jasmine`, `Mocha`, or any other JavaScript testing framework.
A unit testing runner for JavaScript, {% url "Karma" http://karma-runner.github.io/ %}, works with either {% url "Jasmine" https://jasmine.github.io/ %}, { %url "Mocha" http://mochajs.org/ %}, or any other JavaScript testing framework.
Karma also watches your JavaScript files, live reloads when they change, and is also the `reporter` for your tests failing / passing. It runs from the command line.
@@ -28,7 +28,7 @@ Cypress essentially replaces Karma because it does all of this already and much
**Capybara**
The a `Ruby` specific tool that allows you to write integration tests for your web application is {% url "Capybara" http://teamcapybara.github.io/capybara/ %}. In the Rails world, this is the *go-to* tool for testing your application. It uses `Selenium` (or another headless driver) to interact with browsers. It's API consists of commands that query for DOM elements, perform user actions, navigate around, etc.
The a `Ruby` specific tool that allows you to write integration tests for your web application is {% url "Capybara" http://teamcapybara.github.io/capybara/ %}. In the Rails world, this is the *go-to* tool for testing your application. It uses {% url "SauceLabs" https://saucelabs.com/ %} (or another headless driver) to interact with browsers. It's API consists of commands that query for DOM elements, perform user actions, navigate around, etc.
Cypress essentially replaces Capybara because it does all of these things and much more. The difference is that instead of testing your application in a GUI-less console, you'd see your application at all times. You'd never have to take a screenshot to debug because all commands instantly provide you the state of your application while they run. Upon any command failing, you'll get a human-readable error explaining why it failed. There's no "guessing" when debugging.
@@ -60,13 +60,13 @@ Cypress desktop app and CLI are free to use. The Cypress Dashboard is a premium
## {% fa fa-angle-right %} What operating systems do you support?
The desktop application can be installed in OSX and Linux. {% issue 74 'Windows is not yet supported' %}, although you can use Cypress if you install a Linux VM using something like VirtualBox or using a Docker image.
The desktop application can be {% url "installed" installing-cypress %} in OSX and Linux. {% issue 74 'Windows is not yet supported' %}, although you can use Cypress if you install a Linux VM using something like {% url "VirtualBox" https://www.virtualbox.org/ %} or using a {% url "Docker image" userland-extensions#Docker %}.
## {% fa fa-angle-right %} Do you support native mobile apps?
Cypress would never be able to run on a native mobile app, but would be able to run in a web view. In that mode, you'd see the commands display in a browser while you would drive the mobile device separately. Down the road we'll likely have first class support for this, but today it is not a current priority.
Cypress would never be able to run on a native mobile app, but would be able to run in a mobile web browser. In that mode, you'd see the commands display in a browser while you would drive the mobile device separately. Down the road we'll likely have first class support for this, but today it is not a current priority.
Currently you can control the {% url `cy.viewport()` viewport %} to test responsive, mobile views in a website or web application.
Currently you can control the viewport with the {% url `cy.viewport()` viewport %} command to test responsive, mobile views in a website or web application.
## {% fa fa-angle-right %} Do you support X language or X framework?
@@ -76,7 +76,7 @@ You'll write your tests in JavaScript, but beyond that Cypress works everywhere.
## {% fa fa-angle-right %} Will Cypress work in my CI provider?
Cypress works in any CI provider.
Cypress works in any {% url "CI provider" continuous-integration %}.
## {% fa fa-angle-right %} Does Cypress require me to change any of my existing code?
@@ -88,7 +88,7 @@ Yes, technically; it's sandboxed and has to follow the same rules as every other
But Cypress is actually way beyond just a basic JavaScript application running in the browser. It's also a Desktop Application and communicates with backend web services.
All of these technologies together are coordinated and enable Cypress to work, which extends its capabilities far outside of the browser sandbox. Without these, Cypress would not work at all. For the vast majority of your web development, Cypress will work just fine, and already **does** work.
All of these technologies together are coordinated and enable Cypress to work, which extends its capabilities far outside of the browser sandbox. Without these, Cypress would not work at all. For the vast majority of your web development, Cypress will work just fine, and already *does* work.
## {% fa fa-angle-right %} We use WebSockets, will Cypress work with that?
@@ -101,7 +101,7 @@ Yes.
## {% fa fa-angle-right %} We have the craziest most insane authentication system ever, will Cypress work with that?
If you're using some crazy thumb-print, retinal-scan, time-based, key-changing, microphone audial decoding mechanism to log in your users, then no, Cypress won't work with that. But seriously, Cypress is a **development** tool, which makes it easy to test your web applications. If your application is doing 100x things to make it extremely difficult to access, Cypress won't magically make it any easier.
If you're using some crazy thumb-print, retinal-scan, time-based, key-changing, microphone, audial, decoding mechanism to log in your users, then no, Cypress won't work with that. But seriously, Cypress is a *development* tool, which makes it easy to test your web applications. If your application is doing 100x things to make it extremely difficult to access, Cypress won't magically make it any easier.
Because Cypress is a development tool, you can always make your application more accessible while in your development environment. If you want, simply disable crazy steps in your authentication systems while you're in your testing environment. After all, that's why we have different environments! Normally you already have a development environment, a testing environment, a staging environment, and a production environment. So simply expose the parts of your system you want accessible in each appropriate environment.
@@ -111,11 +111,11 @@ Just remember, Cypress won't make a non-testable application suddenly testable.
## {% fa fa-angle-right %} Can I use Cypress to script user-actions on an external site like `gmail.com`?
No. There are already lots of tools to do that. Using Cypress to test against a 3rd party application is not supported. It *may* work but will defeat the purpose of why it was created. You use Cypress *while* you develop *your* application, it helps you write your tests.
No. There are already lots of tools to do that. Using Cypress to test against a 3rd party application is not it's intended use. It *may* work but will defeat the purpose of why it was created. You use Cypress *while* you develop your application, it helps you write your tests.
## {% fa fa-angle-right %} Is there code coverage?
There is nothing currently built into Cypress to do this. Adding code coverage around end to end tests is much harder than unit and its possible it may not be feasible to do in a generic way. You can read in more detail about code coverage {% issue 346 'here' %}.
There is nothing currently built into Cypress to do this. Adding code coverage around end to end tests is much harder than unit tests and it may not be feasible to do in a generic way. You can read in more detail about code coverage {% issue 346 'here' %}.
<!-- ## What kind of tests do I write in Cypress? -->
@@ -124,7 +124,8 @@ There is nothing currently built into Cypress to do this. Adding code coverage a
No. In fact Cypress' architecture is very different from Selenium in a few critical ways:
- Cypress runs in the context of the browser. With Cypress it's much easier to accurately test the browser, but harder to talk to the outside work. In Selenium it's the exact opposite. Although Cypress has a few commands that give you access to the outside world - like {% url `cy.request()` request %} and {% url `cy.exec()` exec %}.
- Cypress runs in the context of the browser. With Cypress it's much easier to accurately test the browser, but harder to talk to the outside work. In Selenium it's the exact opposite, it runs outside of the browser where your application is running. Although Cypress has a few commands that give you access to the outside world - like {% url `cy.request()` request %} and {% url `cy.exec()` exec %}.
- With Selenium - aka WebDriver, you either get 100% simulated events (with Selenium RC) or you got 100% native events with Selenium WebDriver. However, with Cypress, you actually get both. For the most part we use simulated events; We can reproduce them with nearly 100% fidelity, they are much faster, and guaranteed to work the same way every time. However we do use automation API's for things like Cookies where we extend outside of the JavaScript sandbox and interact with the underlying browser API's. This gives us flexibility to determine which type of event to use in specific situations. We've yet to add native input events though.
## {% fa fa-angle-right %} Are there driver bindings in my language?
+28 -27
View File
@@ -18,19 +18,19 @@ You can read more about parallelization {% issue 64 'here' %}.
## {% fa fa-angle-right %} Can I run a single test or group of tests?
You can run a group of tests or a single test by placing an `.only` to a test suite or specific test.
You can run a group of tests or a single test by placing an {% url `.only` organizing-tests#Excluding-and-Including-Tests %} on a test suite or specific test.
You can run a single test headlessly by passing the `--spec` flag to {% url '`cypress run`' cli-tool#cypress-run %}.
You can run a single test file headlessly by passing the `--spec` flag to {% url '`cypress run`' cli-tool#cypress-run %}.
Currently there is no way to specify a group of tests to run headlessly. You can read more {% issue 263 'here' %}.
Currently there is no way to specify a group of test files to run headlessly. You can read more {% issue 263 'here' %}.
## {% fa fa-angle-right %} How do I test uploading a file?
It is possible to upload files in your application but its different based on how you've written your own upload code. You can read more about this {% issue 170 'here' %}
It is possible to upload files in your application but it's different based on how you've written your own upload code. You can read more about this {% issue 170 'here' %}
## {% fa fa-angle-right %} What is the projectId for?
Once you setup your project to record, we generate a unique `projectId` for your project, and automatically insert it into your `cypress.json` file.
Once you {% url "setup your tests to record" dashboard-runs %}, we generate a unique `projectId` for your project and automatically insert it into your `cypress.json` file.
**The `projectId` is a 6 character string in your cypress.json:**
@@ -40,11 +40,11 @@ Once you setup your project to record, we generate a unique `projectId` for your
}
```
This is how we uniquely identify your project. If you manually alter this, *Cypress will no longer be able to identify your project or find the recorded builds for it*. We recommend that you check your `cypress.json` including the `projectId` into source control.
This is how we uniquely identify your project. If you manually alter this, *Cypress will no longer be able to identify your project or find the recorded tests for it*. We recommend that you check your `cypress.json`, including the `projectId`, into source control.
## {% fa fa-angle-right %} What is a Record Key?
Once you're setup to record test runs, we automatically generate a **Record Key** for the project.
Once you're {% url "setup to record test runs" dashboard-runs %}, we automatically generate a *Record Key* for the project.
**A record key is a GUID that looks like this:**
@@ -56,14 +56,14 @@ f4466038-70c2-4688-9ed9-106bf013cd73
You can create multiple Record Keys for a project, or delete existing ones from our {% url 'Dashboard' https://on.cypress.io/dashboard %}.
{% endnote %}
You can also find your Record Key inside of the *Settings* tab.
You can also find your Record Key inside of the *Settings* tab in our Desktop Application.
![Settings Tab of Desktop](https://cloud.githubusercontent.com/assets/1268976/22866094/64aeeb3e-f13e-11e6-93f5-f7420892913f.png)
## {% fa fa-angle-right %} How do I get the native DOM reference of an element found using Cypress?
Cypress wraps elements in jQuery so you'd just get the native element from there.
Cypress wraps elements in jQuery so you'd just get the native element from there within a {% url "`.then()`" then %} command.
```javascript
cy.get('button').then(($el) => {
@@ -75,7 +75,7 @@ cy.get('button').then(($el) => {
## {% fa fa-angle-right %} How do I wait for multiple XHR requests to the same url?
You should set up an alias (using {% url `.as()` as %}) to a single route that matches all of the XHRs. You can then {% url `cy.wait()` wait %} on it multiple times and Cypress keeps track of how many matching XHR requests there are.
You should set up an alias (using {% url `.as()` as %}) to a single {% url `cy.route()` route %} that matches all of the XHRs. You can then {% url `cy.wait()` wait %} on it multiple times. Cypress keeps track of how many matching XHR requests there are.
```javascript
cy.server()
@@ -99,13 +99,13 @@ You could also just stub XHR requests directly using {% url `cy.route()` route %
## {% fa fa-angle-right %} How do I test content inside an iframe?
Currently Cypress does not support selecting or accessing elements from within an iframe. You can read more about this {% issue 136 '#here' %}.
Currently Cypress does not support selecting or accessing elements from within an iframe. You can read more about this {% issue 136 'here' %}.
## {% fa fa-angle-right %} How do I preserve cookies/localstorage in between my tests?
## {% fa fa-angle-right %} How do I preserve cookies / localStorage in between my tests?
By default, Cypress automatically clears all cookies **before** each test to prevent state from building up.
By default, Cypress automatically {% url "clears all cookies **before** each test" clearcookies %} to prevent state from building up.
You can whitelist specific cookies to be preserved across tests:
You can whitelist specific cookies to be preserved across tests using the {% url "Cypress.Cookies api" cookies %}:
```javascript
// now any cookie with the name 'session_id' will
@@ -115,31 +115,32 @@ Cypress.Cookies.defaults({
})
```
You cannot currently preserve localStorage across tests and can read more {% issue 461 'here' %}.
You can *not* currently preserve localStorage across tests and can read more {% issue 461 'here' %}.
## {% fa fa-angle-right %} Some of my elements animate in, how do I work around that?
Oftentimes you can usually account for animation by asserting `.should('be.visible')` or another assertion on one of the elements you expect to be animated in.
Oftentimes you can usually account for animation by asserting {% url "`.should('be.visible')`" should %} or {% url "another assertion" cypress-in-a-nutshell#Assertions %} on one of the elements you expect to be animated in.
```javascript
// assuming a click event causes the animation
cy.get('element').click().should('not.have.class', 'animating')
cy.get('.element').click().should('not.have.class', 'animating')
```
If the animation is especially long, you could extend the time Cypress waits for the assertion to be true by increasing the `timeout`.
If the animation is especially long, you could extend the time Cypress waits for the assertion to pass by increasing the `timeout` of the previous command before the assertion.
```javascript
cy.get('button', { timeout: 10000 }) // <-- wait up to 10 seconds for this 'button' to be found
.should('be.visible') // <-- and to be visible
cy.get('button', { timeout: 10000 }) // wait up to 10 seconds for this 'button' to exist
.should('be.visible') // and to be visible
cy.get('element').click({ timeout: 10000 }).should('not.have.class', 'animating')
cy.get('.element').click({ timeout: 10000 }).should('not.have.class', 'animating')
// wait up to 10 seconds for the .element to not have 'animating' class
```
## {% fa fa-angle-right %} Can I test anchor links that open in a new tab?
Cypress does not and may never have multi-tab support for various reasons.
Luckily there are lots of easy and safe workarounds that enable you to test the behavior of your application
Luckily there are lots of easy and safe workarounds that enable you to test this behavior in your application.
[Read through this recipe to see how to test anchor links.](https://github.com/cypress-io/cypress-example-recipes/blob/master/cypress/integration/tab_handling_anchor_links_spec.js)
@@ -166,7 +167,7 @@ Luckily there are lots of easy and safe workarounds that enable you to test the
## {% fa fa-angle-right %} How do I get an input's value in Cypress?
Cypress DOM elements are just jQuery elements so you can use any method available in jQuery. Below are some examples of working with an input's value.
DOM elements yielded in Cypress are just jQuery elements so you can use any method available in jQuery. Below are some examples of working with an input's value.
```javascript
cy.get('input').invoke('val').then((val) => {
@@ -180,13 +181,13 @@ cy.get('input').then(($input) => {
// make an assertion on the value
cy.get('input').should('have.value', 'abc')
```
```
<!-- ## {% fa fa-angle-right %} How do I make conditional based assertions / control flow? -->
<!-- ## How do I make conditional based assertions / control flow? -->
## {% fa fa-angle-right %} How do I require "" node module in Cypress?
## {% fa fa-angle-right %} How do I require X node module in Cypress?
The code you write in Cypress is executed in the browser, so you can import or require JS modules, but only those that work in the browser.
The code you write in Cypress is executed in the browser, so you can import or require JS modules, *but* only those that work in a browser.
Cypress doesn't have direct access to node or your file system. We recommend utilizing {% url `cy.exec()` exec %} to execute a shell command or a node script that will do what you need.
@@ -3,6 +3,14 @@ title: Userland Extensions
comments: false
---
# Docker
## Base Image
Docker image with dependencies and specific version of Cypress.
{% url "https://hub.docker.com/r/bahmutov/cypress-image/" https://hub.docker.com/r/bahmutov/cypress-image/ %}
# Gitlab
## Multi Cypress
+2 -1
View File
@@ -3,8 +3,9 @@
padding-top: 40px;
}
.toc {
ol.toc {
padding-bottom: 15px;
padding-left: 0;
}
.toc-link {