From 551e38dfdae13aaff613c44ffb8a3d948da01188 Mon Sep 17 00:00:00 2001 From: Jennifer Shehane Date: Tue, 23 Jun 2020 13:12:26 +0630 Subject: [PATCH 1/3] Rename uses of whitelist/blacklist that are not relevant to actual API usage --- .textlintrc | 2 ++ source/_changelogs/0.12.0.md | 2 +- source/_changelogs/0.12.7.md | 2 +- source/_changelogs/0.12.8.md | 3 +-- source/_changelogs/0.17.0.md | 2 +- source/_changelogs/0.19.0.md | 2 +- source/_changelogs/0.5.8.md | 2 +- source/_changelogs/2.0.0.md | 2 +- source/_changelogs/3.1.1.md | 2 +- source/_changelogs/3.2.0.md | 4 ++-- ...nfig_whitelist.md => allowed_test_config.md} | 0 ...pn_whitelist_list.md => vpn_allowed_list.md} | 2 +- source/api/commands/server.md | 12 ++++++------ source/api/cypress-api/cookies.md | 16 ++++++++-------- source/api/cypress-api/cypress-server.md | 2 +- source/faq/questions/dashboard-faq.md | 4 ++-- source/faq/questions/using-cypress-faq.md | 2 +- .../writing-and-organizing-tests.md | 4 ++-- source/guides/guides/network-requests.md | 2 +- source/guides/references/configuration.md | 12 ++++++------ source/guides/references/troubleshooting.md | 8 ++++---- .../{blacklist-host.png => blocked-host.png} | Bin 22 files changed, 44 insertions(+), 43 deletions(-) rename source/_partial/{test_config_whitelist.md => allowed_test_config.md} (100%) rename source/_partial/{vpn_whitelist_list.md => vpn_allowed_list.md} (85%) rename themes/cypress/source/img/guides/{blacklist-host.png => blocked-host.png} (100%) diff --git a/.textlintrc b/.textlintrc index 26986269fa..fcfa43610b 100644 --- a/.textlintrc +++ b/.textlintrc @@ -86,6 +86,8 @@ ["craziest", "most complex"], ["dumb", "unintended"], ["insane", "outrageous"], + ["blacklist", "blocklist"], + ["whitelist", "allow"], // Prefer American spelling ["behaviour", "behavior"], diff --git a/source/_changelogs/0.12.0.md b/source/_changelogs/0.12.0.md index c79196a7ca..dbdcf5c051 100644 --- a/source/_changelogs/0.12.0.md +++ b/source/_changelogs/0.12.0.md @@ -40,7 +40,7 @@ - Any issues related to `requestJSON` or `responseJSON` being duplicated are now fixed. Fixes {% issue 65 '#65' %}. - Fully Qualified XHR's which should be proxied are now correctly transparently rewritten to prevent CORS problems. - {% url `cy.route()` route %} - `onRequest` and `onResponse` callbacks are now called with `cy` as the context. -- Whitelisting assets which should never be stubbed has been improved. Now `.jsx` templates pass-through correctly. +- Filtering assets which should never be stubbed has been improved. Now `.jsx` templates pass-through correctly. - CORS Network Errors are now correctly caught. **Misc:** diff --git a/source/_changelogs/0.12.7.md b/source/_changelogs/0.12.7.md index 71a78cbd7a..70eaf7ce30 100644 --- a/source/_changelogs/0.12.7.md +++ b/source/_changelogs/0.12.7.md @@ -5,6 +5,6 @@ **Bugfixes:** - Prevent passing `{multiple: true}` incorrectly showing up in Command Log. Fixes {% issue 88 '#88' %}. -- Properly whitelist resource like XHR's which have query params such as jquery's `{cache: false}` option. +- Properly allow resource like XHR's which have query params such as jquery's `{cache: false}` option. - Correctly take into account `` tag on XHR's. Fixes {% issue 89 '#89' %}. diff --git a/source/_changelogs/0.12.8.md b/source/_changelogs/0.12.8.md index c6d5bb9d16..64f29b812f 100644 --- a/source/_changelogs/0.12.8.md +++ b/source/_changelogs/0.12.8.md @@ -13,5 +13,4 @@ - Rewrote error message which is displayed when Cypress cannot parse your test / spec file. Now a list of suggestions are given and an external link is provided which further explains how this may happen. - Clarified the "Default Message" page when you have not {% url `cy.visit()` visit %} your application yet. -- Whitelisted `.coffee`, `.scss`, `.less` XHR's from displaying in the Command Log. - +- Ignored `.coffee`, `.scss`, `.less` XHR's from displaying in the Command Log. diff --git a/source/_changelogs/0.17.0.md b/source/_changelogs/0.17.0.md index 1b08ebbaff..891f36acf2 100644 --- a/source/_changelogs/0.17.0.md +++ b/source/_changelogs/0.17.0.md @@ -14,7 +14,7 @@ **Features:** -- *All CORS related issues should finally be fixed now.* Cypress now internally switches to the domain that you used in your {% url `cy.visit()` visit %}. This means that the correct domain will display in the URL based on the application currently under test. Your application's code will run under the current domain at all times. Previously we implemented an endless amount of hacks and internal translations to figure out the domain you were *supposed* to be on without actually being on the domain. This caused code to behave different and caused subtle issues. Those issues should now be resolved. The entire proxy layer has been rewritten to handle all HTTPS certificates flawlessly, continue to inject (even on HTTPS pages), and still know when to automatically bypass injection so you can open other tabs while testing in Cypress. These new proxy changes also unlock the ability to do things like whitelisting or blacklisting specific 3rd party domains, or even be able to stub not just XHR's but any kind of HTTP request. +- *All CORS related issues should finally be fixed now.* Cypress now internally switches to the domain that you used in your {% url `cy.visit()` visit %}. This means that the correct domain will display in the URL based on the application currently under test. Your application's code will run under the current domain at all times. Previously we implemented an endless amount of hacks and internal translations to figure out the domain you were *supposed* to be on without actually being on the domain. This caused code to behave different and caused subtle issues. Those issues should now be resolved. The entire proxy layer has been rewritten to handle all HTTPS certificates flawlessly, continue to inject (even on HTTPS pages), and still know when to automatically bypass injection so you can open other tabs while testing in Cypress. These new proxy changes also unlock the ability to do things like allowing or blocking specific 3rd party domains, or even be able to stub not just XHR's but any kind of HTTP request. - `window.fetch` now works correctly. Stubbing these does not yet work but it is now possible for us to implement stubbing in a future version. Addresses {% issue 95 '#95' %}. - The list of tests now automatically refresh when test files are renamed, deleted, or added. In addition, because the list of tests is now displayed in the desktop application, we now synchronize the state of the current running spec. - {% url `cy.visit()` visit %} has better error messages. Cypress now programmatically determines why a {% url `cy.visit()` visit %} failed and gives you a ridiculously accurate error message. Addresses {% issue 138 '#138' %}. diff --git a/source/_changelogs/0.19.0.md b/source/_changelogs/0.19.0.md index e479c90863..d646660dd8 100644 --- a/source/_changelogs/0.19.0.md +++ b/source/_changelogs/0.19.0.md @@ -24,7 +24,7 @@ - There is a new {% url 'Dashboard' https://on.cypress.io/dashboard %} service that displays your recorded runs. - The {% url 'Dashboard' https://on.cypress.io/dashboard %} enables you to view your recorded runs, manage projects, create organizations, invite users and set permissions. - Projects are either **public** with their runs being publicly viewable by anyone, or **private** which restricts their access to only users you've invited. All **existing** projects were set to **private** by default. -- When you invite users (from the Dashboard) we will **automatically** whitelist them. This means you can invite all of your teammates (or anyone else). They can start using Cypress without talking to us. +- When you invite users (from the Dashboard) we will **automatically** allow them. This means you can invite all of your teammates (or anyone else). They can start using Cypress without talking to us. - We now list all of the recorded runs directly in the Test Runner under a new `Runs` tab. Fixes {% issue 236 '#236' %}. - Your list of projects in the Test Runner now displays their last recorded run status - passing, failing, pending, running, etc. - We've changed the "Config" tab to now be called "Settings". We added two new sections to the "Settings" tab which displays your `projectId` and your Record Key. These sections do a much better job explaining what these are and how you use them. diff --git a/source/_changelogs/0.5.8.md b/source/_changelogs/0.5.8.md index 8266668bca..d65108be89 100644 --- a/source/_changelogs/0.5.8.md +++ b/source/_changelogs/0.5.8.md @@ -6,7 +6,7 @@ - {% url `.as()` as %} can now alias primitives and objects other than routes or DOM. - {% url `.as()` as %} automatically assigns this alias to `runnable.ctx` which makes it available synchronously. -- {% url `.as()` as %} blacklists several reserved words and will throw if you attempt to alias as one of them. +- {% url `.as()` as %} does not allow several reserved words and will throw if you attempt to alias as one of them. - {% url `cy.get()` get %} can now accept all alias types and will display the labels in the UI differently based on the alias type. - Cypress now displays a message when the Desktop App update is actually being applied instead of doing nothing and looking like it's crashed. diff --git a/source/_changelogs/2.0.0.md b/source/_changelogs/2.0.0.md index 458034d9e6..02a138e0d3 100644 --- a/source/_changelogs/2.0.0.md +++ b/source/_changelogs/2.0.0.md @@ -11,7 +11,7 @@ **Bugfixes:** -- {% url "`blacklistHosts`" configuration#Browser %} would occasionally not work if you were blacklisting a host that had previously cached a file. In this case, the browser would serve it from disk and not make an actual HTTP request. This issue has been solved by clearing the cache when the browser opens. Fixes {% issue 1154 %}. +- {% url "`blacklistHosts`" configuration#Browser %} would occasionally not work if you were blocking a host that had previously cached a file. In this case, the browser would serve it from disk and not make an actual HTTP request. This issue has been solved by clearing the cache when the browser opens. Fixes {% issue 1154 %}. - {% url "`blacklistHosts`" configuration#Browser %} is now correctly accepted via the `--config` CLI flag. - Spies and Stubs created with {% url "`cy.stub()`" stub %} and {% url "`cy.spy()`" spy %} will now retry their assertions when utilized from an {% url "alias" as %}. Fixes {% issue 1156 %}. - Basic auth is working again in Chrome 63 and Chrome 64. We "for real" fixed it this time by adding auth headers automatically at the network proxy layer and bypassed the browser altogether. We automatically apply auth headers if you provide a username/password in the URL of a `cy.visit(url)`. We also added a new `auth` option to specify the `username/password` using `cy.visit(url, options)`. All of the requests that match the origin of the URL will have the `Authorization: Basic <...>` headers added. Fixes {% issue 1288 %}. diff --git a/source/_changelogs/3.1.1.md b/source/_changelogs/3.1.1.md index d5115efdec..63d3b2549f 100644 --- a/source/_changelogs/3.1.1.md +++ b/source/_changelogs/3.1.1.md @@ -33,7 +33,7 @@ - The Test Runner's search now resets when switching between projects. Fixes {% issue 2512 %}. - Fixed internal Cypress tests. Fixes {% issue 2606 %}. - Replaced use of `new Buffer` with `Buffer.from`. Fixes {% issue 2626 %}. -- Whitelisted `autoScrollingEnabled` to be saved in `state.json`. Fixes {% issue 2476 %}. +- Allowed `autoScrollingEnabled` to be saved in `state.json`. Fixes {% issue 2476 %}. - Fixed internal test error `beforeSpecRun is not a function`. Fixes {% issue 2401 %}. - Switched our internal tests to use CircleCI workspaces. Fixes {% issue 2398 %}. - Update TypeScript definition for {% url "`cy.screenshot()`" screenshot %} to include screenshot specific options. Fixes {% issue 2654 %}. diff --git a/source/_changelogs/3.2.0.md b/source/_changelogs/3.2.0.md index 4dd03af638..da69754dda 100644 --- a/source/_changelogs/3.2.0.md +++ b/source/_changelogs/3.2.0.md @@ -8,7 +8,7 @@ - {% url "`cy.request()`" request %} now allows any valid HTTP `method` to be used including `TRACE`, `COPY`, `LOCK`, `MKCOL`, `MOVE`, `PURGE`, `PROPFIND`, `PROPPATCH`, `UNLOCK`, `REPORT`, `MKACTIVITY`, `CHECKOUT`, `MERGE`, `M-SEARCH`, `NOTIFY`, `SUBSCRIBE`, `UNSUBSCRIBE`, `SEARCH`, and `CONNECT`. Addresses {% issue 1302 %} - The {% url "`--browser` argument" command-line#cypress-run-browser-lt-browser-name-or-path-gt %} of the {% url "Command Line" command-line %} and the {% url "`browser` argument" module-api#cypress-run %} of the {% url "Module API" module-api %} have been updated to allow passing a ``. Addresses {% issue 1026 %}. - {% url "`cy.type()`" type %} now accepts `{home}` and `{end}` special character sequences to move the cursor to the start or end of a line. Addresses {% issue 2033 %}. -- The Cypress Chrome extension now has a static ID of `caljajdfkjjjdehjdoimjkkakekklcck`. This allows Cypress to be added to extension whitelists for those working under corporate policies that prohibit extensions. Addresses {% issue 3673 %}, {% issue 1239 %} and {% issue 2494 %}. +- The Cypress Chrome extension now has a static ID of `caljajdfkjjjdehjdoimjkkakekklcck`. This allows Cypress to be added to your allowed extensions for those working under corporate policies that prohibit extensions. Addresses {% issue 3673 %}, {% issue 1239 %} and {% issue 2494 %}. **Bugfixes:** @@ -46,7 +46,7 @@ - Updated {% url "docs" launching-browsers %} on explain how to run Chrome and Chromium browsers {% url "#1339" https://github.com/cypress-io/cypress-documentation/issues/1339 %} - Added `{home}` and `{end}` character sequences to {% url "cy.type()" type } doc. Also wrote better description of what `{downarrow}` and `{uparrow}` character sequences actually do. {% url "#1347" https://github.com/cypress-io/cypress-documentation/pull/1347 %} - Added all newly supported HTTP methods to {% url "`cy.request()`" request %} doc. -- Add new section to {% url "Debugging" debugging#Chrome-extension-whitelisting %} doc explaining whitelisting the Cypress Chrome extension. +- Add new section to {% url "Troubleshooting" troubleshooting#Allow-the-Cypress-Chrome-extension %} doc explaining how to allow the Cypress Chrome extension. - Fixed code example for google analytics stubbing {% url "#1454" https://github.com/cypress-io/cypress-documentation/issues/1454 %} **Dependency Updates** diff --git a/source/_partial/test_config_whitelist.md b/source/_partial/allowed_test_config.md similarity index 100% rename from source/_partial/test_config_whitelist.md rename to source/_partial/allowed_test_config.md diff --git a/source/_partial/vpn_whitelist_list.md b/source/_partial/vpn_allowed_list.md similarity index 85% rename from source/_partial/vpn_whitelist_list.md rename to source/_partial/vpn_allowed_list.md index 60b4ed8529..a6d70852e6 100644 --- a/source/_partial/vpn_whitelist_list.md +++ b/source/_partial/vpn_allowed_list.md @@ -1,6 +1,6 @@ To send the data and results of your tests to the [Dashboard](https://on.cypress.io/dashboard-introduction), Cypress needs free access to some URLs. -If you are running the tests from within a restrictive VPN you will need to add some URLs to your whitelist so that Cypress can have effective communication with the Dashboard. +If you are running the tests from within a restrictive VPN you will need to allow some URLs so that Cypress can have effective communication with the Dashboard. **The URLs are the following:** diff --git a/source/api/commands/server.md b/source/api/commands/server.md index c3ed4e3da0..17b206cd67 100644 --- a/source/api/commands/server.md +++ b/source/api/commands/server.md @@ -57,7 +57,7 @@ Option | Default | Description `onAnyRequest` | `undefined` | callback function called when any request is sent `onAnyResponse` | `undefined` | callback function called when any response is returned `urlMatchingOptions` | `{ matchBase: true }` | The default options passed to `minimatch` when using glob strings to match URLs -`whitelist` | function | Callback function that whitelists requests from ever being logged or stubbed. By default this matches against asset-like requests such as for `.js`, `.jsx`, `.html`, and `.css` files. +`whitelist` | function | Callback function that filters requests from ever being logged or stubbed. By default this matches against asset-like requests such as for `.js`, `.jsx`, `.html`, and `.css` files. ## Yields {% helper_icon yields %} @@ -69,8 +69,8 @@ Option | Default | Description ### After starting a server: -- Any request that does **NOT** match a {% url `cy.route()` route %} will {% url 'pass through to the server' network-requests#Don’t-Stub-Responses %}. -- Any request that matches the `options.whitelist` function will **NOT** be logged or stubbed. In other words it is "whitelisted" and ignored. +- Any request that does **NOT** match a {% url `cy.route()` route %} will {% url 'pass through to the server' network-requests#Don't-Stub-Responses %}. +- Any request that matches the `options.whitelist` function will **NOT** be logged or stubbed. In other words it is filtered and ignored. - You will see requests named as `(XHR Stub)` or `(XHR)` in the Command Log. ```javascript @@ -179,7 +179,7 @@ cy.server({ }) ``` -### Change the default whitelisting +### Change the default filtering `cy.server()` comes with a `whitelist` function that by default filters out any requests that are for static assets like `.html`, `.js`, `.jsx`, and `.css`. @@ -187,12 +187,12 @@ Any request that passes the `whitelist` will be ignored - it will not be logged The idea is that we never want to interfere with static assets that are fetched via Ajax. -**The default whitelist function in Cypress is:** +**The default filter function in Cypress is:** ```javascript const whitelist = (xhr) => { // this function receives the xhr object in question and - // will whitelist if it's a GET that appears to be a static resource + // will filter if it's a GET that appears to be a static resource return xhr.method === 'GET' && /\.(jsx?|html|css)(\?.*)?$/.test(xhr.url) } ``` diff --git a/source/api/cypress-api/cookies.md b/source/api/cypress-api/cookies.md index 8ba941580d..d0cd9b0c42 100644 --- a/source/api/cypress-api/cookies.md +++ b/source/api/cypress-api/cookies.md @@ -8,7 +8,7 @@ title: Cypress.Cookies Cypress automatically clears all cookies **before** each test to prevent state from building up. -You can take advantage of `Cypress.Cookies.preserveOnce()` or even *whitelist* cookies by their name to preserve values across multiple tests. This enables you to preserve sessions through several tests. +You can take advantage of `Cypress.Cookies.preserveOnce()` or even preserve cookies by their name to preserve values across multiple tests. This enables you to preserve sessions through several tests. # Syntax @@ -30,7 +30,7 @@ Names of cookies to be preserved. Pass an unlimited number of arguments. **{% fa fa-angle-right %} options** ***(Object)*** -Set defaults for all cookies, such as whitelisting a set of cookies to bypass being cleared before each test. +Set defaults for all cookies, such as preserving a set of cookies to bypass being cleared before each test. # Examples @@ -121,7 +121,7 @@ describe('Dashboard', () => { ### Set global default cookies -You can modify the global defaults and whitelist a set of Cookies which will always be preserved across tests. +You can modify the global defaults and preserve a set of Cookies which will always be preserved across tests. Any change you make here will take effect immediately for the remainder of every single test. @@ -129,14 +129,14 @@ Any change you make here will take effect immediately for the remainder of every A great place to put this configuration is in your `cypress/support/index.js` file, since it is loaded before any test files are evaluated. {% endnote %} -### Whitelist accepts: +### `whitelist` accepts: - String - Array - RegExp - Function -### Whitelist String +### Preserve String ```javascript // now any cookie with the name 'session_id' will @@ -146,7 +146,7 @@ Cypress.Cookies.defaults({ }) ``` -### Whitelist Array +### Preserve Array ```javascript // now any cookie with the name 'session_id' or 'remember_token' @@ -156,7 +156,7 @@ Cypress.Cookies.defaults({ }) ``` -### Whitelist RegExp +### Preserve RegExp ```javascript // now any cookie that matches this RegExp @@ -166,7 +166,7 @@ Cypress.Cookies.defaults({ }) ``` -### Whitelist Function +### Preserve Function ```javascript Cypress.Cookies.defaults({ diff --git a/source/api/cypress-api/cypress-server.md b/source/api/cypress-api/cypress-server.md index a023edd458..5052eca7cf 100644 --- a/source/api/cypress-api/cypress-server.md +++ b/source/api/cypress-api/cypress-server.md @@ -29,7 +29,7 @@ Cypress.Server.defaults({ delay: 500, force404: false, whitelist: (xhr) => { - // handle custom logic for whitelisting + // handle custom logic for filtering XHR requests } }) ``` diff --git a/source/faq/questions/dashboard-faq.md b/source/faq/questions/dashboard-faq.md index ccdc1a0e06..b67d9bcbd7 100644 --- a/source/faq/questions/dashboard-faq.md +++ b/source/faq/questions/dashboard-faq.md @@ -134,6 +134,6 @@ In order to avoid any interruption in service, we recommend that you review your 4. Review your organization’s usage 5. Scroll down and select *Upgrade* under your plan of choice -## {% fa fa-angle-right %} I'm working at a restrictive VPN. Which subdomains do I have to whitelist on my VPN for the Dashboard to work properly? +## {% fa fa-angle-right %} I'm working at a restrictive VPN. Which subdomains do I have to allow on my VPN for the Dashboard to work properly? -{% partial vpn_whitelist_list %} +{% partial vpn_allowed_list %} diff --git a/source/faq/questions/using-cypress-faq.md b/source/faq/questions/using-cypress-faq.md index 111d260b98..aaba338a81 100644 --- a/source/faq/questions/using-cypress-faq.md +++ b/source/faq/questions/using-cypress-faq.md @@ -414,7 +414,7 @@ We have an {% issue 685 'open proposal' %} to expand the APIs to support "switch 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 using the {% url "Cypress.Cookies api" cookies %}: +You can preserve specific cookies across tests using the {% url "Cypress.Cookies api" cookies %}: ```javascript // now any cookie with the name 'session_id' will diff --git a/source/guides/core-concepts/writing-and-organizing-tests.md b/source/guides/core-concepts/writing-and-organizing-tests.md index e1627731e2..4210a10ab8 100644 --- a/source/guides/core-concepts/writing-and-organizing-tests.md +++ b/source/guides/core-concepts/writing-and-organizing-tests.md @@ -293,9 +293,9 @@ it(name, config, fn) specify(name, config, fn) ``` -### Whitelisted config values +### Allowed config values -{% partial test_config_whitelist %} +{% partial allowed_test_config %} ### Suite of test configuration diff --git a/source/guides/guides/network-requests.md b/source/guides/guides/network-requests.md index 9010acd3e9..6ead69a144 100644 --- a/source/guides/guides/network-requests.md +++ b/source/guides/guides/network-requests.md @@ -118,7 +118,7 @@ Cypress automatically indicates when an XHR request happens in your application. {% imgTag /img/guides/network-requests/snapshot-of-request-command.gif "Snapshot of request and response" %} -By default, Cypress is configured to *ignore* requests that are used to fetch static content like `.js` or `.html` files. This keeps the Command Log less noisy. This option can be changed by overriding the default whitelisting in the {% url '`cy.server()` options' server#Options %}. +By default, Cypress is configured to *ignore* requests that are used to fetch static content like `.js` or `.html` files. This keeps the Command Log less noisy. This option can be changed by overriding the default filtering in the {% url '`cy.server()` options' server#Options %}. Cypress automatically collects the request `headers` and the request `body` and will make this available to you. diff --git a/source/guides/references/configuration.md b/source/guides/references/configuration.md index d85da6a827..28d92010f7 100644 --- a/source/guides/references/configuration.md +++ b/source/guides/references/configuration.md @@ -211,7 +211,7 @@ To apply specific Cypress {% url "configuration" configuration %} values to a su The configuration values passed in will only take effect during the suite or test where they are set. The values will then reset to the previous default values after the suite or test is complete. -{% partial test_config_whitelist %} +{% partial allowed_test_config %} ### Suite configuration @@ -258,13 +258,13 @@ When you open a Cypress project, clicking on the **Settings** tab will display t # Notes -## blacklistHosts +## `blacklistHosts` By passing a string or array of strings you can block requests made to one or more hosts. To see a working example of this please check out our {% url 'Stubbing Google Analytics Recipe' recipes#Stubbing-and-spying %}. -To blacklist a host: +To block a host: - {% fa fa-check-circle green %} Pass only the host - {% fa fa-check-circle green %} Use wildcard `*` patterns @@ -274,7 +274,7 @@ To blacklist a host: {% note info %} Not sure what a part of the URL a host is? {% url 'Use this guide as a reference.' https://nodejs.org/api/url.html#url_url_strings_and_url_objects %} -When blacklisting a host, we use {% url `minimatch` minimatch %} to check the host. When in doubt you can test whether something matches yourself. +When blocking a host, we use {% url `minimatch` minimatch %} to check the host. When in doubt you can test whether something matches yourself. {% endnote %} Given the following URLs: @@ -285,7 +285,7 @@ https://www.google-analytics.com/ga.js http://localhost:1234/some/user.json ``` -This would match the following blacklisted hosts: +This would match the following blocked hosts: ```text www.google-analytics.com @@ -309,7 +309,7 @@ For instance given a URL: `https://google.com/search?q=cypress` When Cypress blocks a request made to a matching host, it will automatically send a `503` status code. As a convenience it also sets a `x-cypress-matched-blacklist-host` header so you can see which rule it matched. -{% imgTag /img/guides/blacklist-host.png "Network tab of dev tools with analytics.js request selected and the response header 'x-cypress-matched-blacklisted-host: www.google-analytics.com' highlighted " %} +{% imgTag /img/guides/blocked-host.png "Network tab of dev tools with analytics.js request selected and the response header highlighted " %} ## modifyObstructiveCode diff --git a/source/guides/references/troubleshooting.md b/source/guides/references/troubleshooting.md index e2062c173c..cd10068422 100644 --- a/source/guides/references/troubleshooting.md +++ b/source/guides/references/troubleshooting.md @@ -101,17 +101,17 @@ To make a browser installed at a different path be auto-detected, create a symbo {% url 'Read more about creating symbolic links on Windows' https://www.howtogeek.com/howto/16226/complete-guide-to-symbolic-links-symlinks-on-windows-or-linux/ %} -# Chrome extension whitelisting +# Allow the Cypress Chrome extension -Cypress utilizes a Chrome extension within the Test Runner in order to run properly. If you or your company whitelist specific Chrome extensions, this may cause problems with running Cypress. You will want to ask your administrator to whitelist the Cypress extension ID below: +Cypress utilizes a Chrome extension within the Test Runner in order to run properly. If you or your company block specific Chrome extensions, this may cause problems with running Cypress. You will want to ask your administrator to allow the Cypress extension ID below: ```sh caljajdfkjjjdehjdoimjkkakekklcck ``` -# URL whitelisting on VPNs +# Allow Cypress URLs on VPNs -{% partial vpn_whitelist_list %} +{% partial vpn_allowed_list %} # Clear App Data diff --git a/themes/cypress/source/img/guides/blacklist-host.png b/themes/cypress/source/img/guides/blocked-host.png similarity index 100% rename from themes/cypress/source/img/guides/blacklist-host.png rename to themes/cypress/source/img/guides/blocked-host.png From f2bd613da1b26efcb19957353cb42f405e74b905 Mon Sep 17 00:00:00 2001 From: Jennifer Shehane Date: Tue, 23 Jun 2020 13:20:09 +0630 Subject: [PATCH 2/3] Fix inadvertently broken link --- source/api/commands/server.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/api/commands/server.md b/source/api/commands/server.md index 17b206cd67..aef407b912 100644 --- a/source/api/commands/server.md +++ b/source/api/commands/server.md @@ -69,7 +69,7 @@ Option | Default | Description ### After starting a server: -- Any request that does **NOT** match a {% url `cy.route()` route %} will {% url 'pass through to the server' network-requests#Don't-Stub-Responses %}. +- Any request that does **NOT** match a {% url `cy.route()` route %} will {% url 'pass through to the server' network-requests#Don’t-Stub-Responses %}. - Any request that matches the `options.whitelist` function will **NOT** be logged or stubbed. In other words it is filtered and ignored. - You will see requests named as `(XHR Stub)` or `(XHR)` in the Command Log. From 330a548dc978be1ae91833fed4cac7dbf31a5904 Mon Sep 17 00:00:00 2001 From: Jennifer Shehane Date: Tue, 23 Jun 2020 14:19:51 +0630 Subject: [PATCH 3/3] Remove old translated files that are not up to date. --- source/ja/faq/questions/company-faq.md | 14 - source/ja/faq/questions/dashboard-faq.md | 103 ---- source/ja/faq/questions/using-cypress-faq.md | 586 ------------------- source/zh-cn/guides/guides/debugging.md | 426 -------------- 4 files changed, 1129 deletions(-) delete mode 100644 source/ja/faq/questions/company-faq.md delete mode 100644 source/ja/faq/questions/dashboard-faq.md delete mode 100644 source/ja/faq/questions/using-cypress-faq.md delete mode 100644 source/zh-cn/guides/guides/debugging.md diff --git a/source/ja/faq/questions/company-faq.md b/source/ja/faq/questions/company-faq.md deleted file mode 100644 index a84883ad54..0000000000 --- a/source/ja/faq/questions/company-faq.md +++ /dev/null @@ -1,14 +0,0 @@ ---- -layout: toc-top -title: 会社についての質問 - -containerClass: faq ---- - -## {% fa fa-angle-right %} Who’s behind Cypress? - -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? - -Yes! You can check our open positions and apply {% url "here" https://www.cypress.io/jobs/ %}. diff --git a/source/ja/faq/questions/dashboard-faq.md b/source/ja/faq/questions/dashboard-faq.md deleted file mode 100644 index 48c66b4210..0000000000 --- a/source/ja/faq/questions/dashboard-faq.md +++ /dev/null @@ -1,103 +0,0 @@ ---- -layout: toc-top -title: ダッシュボードについての質問 -containerClass: faq ---- - -## {% fa fa-angle-right %} What is the Dashboard? - -{% imgTag /img/dashboard/dashboard-runs-list.png "Dashboard Screenshot" %} - -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-introduction%}. - -## {% fa fa-angle-right %} How do I record my tests? - -1. First {% url 'set up the project to record' projects#Setup %}. -2. Then {% url 'record your runs' runs %}. - -After recording your tests, you will see them in the {% url 'Dashboard' https://on.cypress.io/dashboard %} and in the "Runs" tab of the Test Runner. - -## {% fa fa-angle-right %} How much does it cost? - -Please see our {% url 'Pricing Page' https://www.cypress.io/pricing %} for more details. - -## {% 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, screenshots, and videos for public projects. - -**A private project** means that only {% url 'users' users %} you explicitly invite to your {% url 'organization' 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. - -## {% fa fa-angle-right %} How is this different than CI? - -Cypress is **complementary** to your {% url "CI provider" continuous-integration %}, and plays a completely different role. - -It doesn't replace or change anything related to CI. You will run Cypress tests in your CI provider. - -The difference between our {% url 'Dashboard Service' dashboard-introduction%} and your CI provider is that your CI provider has no idea what is going on inside of the Cypress process. It's programmed to know whether or not a process failed - based on whether it had an exit code greater than `0`. - -Our {% url 'Dashboard Service' dashboard-introduction%} 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 %}, 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? - -No, although we are looking to build an on-premise version of the Dashboard for use in private clouds. If you're interested in our on-premise version, [let us know](mailto:hello@cypress.io)! - -## {% fa fa-angle-right %} Can I choose not to use the Dashboard? - -Of course. The Dashboard Service is a separate service from the Test Runner 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 always run your tests in CI using {% url "`cypress run`" command-line#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 does Cypress record? - -We capture the following: - -- Standard Output -- Test Failures -- Screenshots -- Video - -We have already begun the implementation for capturing even more things from your run such as: - -- Commands -- Network Traffic -- Browser Console Logs - -These will be added in subsequent releases. - -## {% fa fa-angle-right %} Why is test parallelization based on spec files and not on the individual functions? - -Cypress {% url "test parallelization" parallelization %} is indeed based on specs. For each spec the Test Runner scaffolds the new running context, in a sense isolating each spec file from any previous spec files, and ensuring a clean slate for the next spec. Doing this for each _individual_ test would be very very expensive and would slow down the test runs significantly. - -Spec file durations are also more meaningful and consistent than timings of individual tests, we can order specs by the moving average of the previously recorded durations. This would be much less useful when load balancing quickly finishing individual tests. - -To better load balance the specs, thus you would want more spec files with approximately the same running duration. Otherwise, a single very long running test might limit how fast all your tests finish, and the run completes. Due to starting a new test execution context before each spec file and encoding and uploading video after, making spec files to run shorter than approximately 10 seconds would also be fruitless - because Cypress overhead would eat any time savings. - -## {% fa fa-angle-right %} My CI setup is based on Docker, but is very custom. How can I load balance my test runs? - -Even if your CI setup is very different from the {% url "CI examples we have" continuous-integration#Examples %} and {% url "run with our sample projects" https://github.com/cypress-io/cypress-example-kitchensink#ci-status %}, you can still take advantage of the test load balancing using the Dashboard. Find a variable across your containers that is the same for all of them, but is different from run to run. For example it could be an environment variable called `CI_RUN_ID` that you set when creating the containers to run Cypress. You can pass this variable via CLI argument {% url `--ci-build-id` command-line#cypress-run-ci-build-id-lt-id-gt %}when starting Cypress in each container: - -```shell -cypress run --record --parallel --ci-build-id $CI_RUN_ID -``` - -For reference, here are {% url "the variables" https://github.com/cypress-io/cypress/blob/develop/packages/server/lib/util/ci_provider.coffee %} we extract from the popular CI providers, and for most of them there is some variable than is set to the same value across multiple containers running in parallel. If there is NO common variable, try using the commit SHA string. Assuming you do not run the same tests more than once against the same commit, it might just be good enough for the job. - -## {% fa fa-angle-right %} Can I delete a run from the Dashboard? - -We are working on implementing run deletion. {% url "Track the issue." https://github.com/cypress-io/cypress/issues/1839 %} - -**Note:** Deleting the recorded runs would have no effect on the amount of tests recorded and counted as your usage billed for the month. - -## {% fa fa-angle-right %} Can I delete my Cypress account? - -You can delete your Cypress account from {% url "your Dashboard profile" https://dashboard.cypress.io/#/profile %}. Deleting your account cannot be undone! By deleting your Cypress account, all associated data in your account will be permanently deleted. - -## {% fa fa-angle-right %} What happens to my Dashboard if I downgrade my account? - -Downgrading your account will **not** result in loss of access to your Dashboard. - -However, it will make your Dashboard subject to the limitations of your new plan. For example, downgrading to the *Seed* plan will limit data retention to 30 days and test recordings to 500 per billing period. diff --git a/source/ja/faq/questions/using-cypress-faq.md b/source/ja/faq/questions/using-cypress-faq.md deleted file mode 100644 index 195462b750..0000000000 --- a/source/ja/faq/questions/using-cypress-faq.md +++ /dev/null @@ -1,586 +0,0 @@ ---- -layout: toc-top -title: Cypressについての質問 -containerClass: faq ---- - -## {% fa fa-angle-right %} How do I get an element's text contents? - -Cypress commands yield jQuery objects, so you can call methods on them. - -If you're just trying to assert on an element's text content: - -```javascript -cy.get('div').should('have.text', 'foobarbaz') -``` - -If you'd like to work with the text prior to an assertion: - -```javascript -cy.get('div').should(($div) => { - const text = $div.text() - - expect(text).to.match(/foo/) - expect(text).to.include('foo') - expect(text).not.to.include('bar') -}) -``` - -If you need to hold a reference or compare values of text: - -```javascript -cy.get('div').invoke('text').then((text1) => { - // do more work here - - // click the button which changes the div's text - cy.get('button').click() - - // grab the div again and compare its previous text - // to the current text - cy.get('div').invoke('text').should((text2) => { - expect(text1).not.to.eq(text2) - }) -}) -``` - -jQuery's `.text()` method automatically calls `elem.textContent` under the hood. If you'd like to instead use `innerText` you can do the following: - -```javascript -cy.get('div').should(($div) => { - // access the native DOM element - expect($div.get(0).innerText).to.eq('foobarbaz') -}) -``` - -This is the equivalent of Selenium's `getText()` method, which returns the innerText of a visible element. - -## {% fa fa-angle-right %} How do I get an input's value? - -Cypress yields you jQuery objects, so you can call methods on them. - -If you're just trying to assert on an input's value: - -```javascript -// make an assertion on the value -cy.get('input').should('have.value', 'abc') -``` - -If you'd like to massage or work with the text prior to an assertion: - -```javascript -cy.get('input').should(($input) => { - const val = $input.val() - - expect(val).to.match(/foo/) - expect(val).to.include('foo') - expect(val).not.to.include('bar') -}) -``` - -If you need to hold a reference or compare values of text: - -```javascript -cy.get('input').invoke('val').then((val1) => { - // do more work here - - // click the button which changes the input's value - cy.get('button').click() - - // grab the input again and compare its previous value - // to the current value - cy.get('input').invoke('val').should((val2) => { - expect(val1).not.to.eq(val2) - }) -}) -``` - -## {% fa fa-angle-right %} How do I compare the value or state of one thing to another? - -Our {% url 'Variables and Aliases guide' variables-and-aliases %} gives you examples of doing exactly that. - -## {% fa fa-angle-right %} Can I store an attribute's value in a constant or a variable for later use? - -Yes, and there are a couple of ways to do this. One way to hold a value or reference is with {% url '`closures`' variables-and-aliases#Closures %}. -Commonly, users believe they have a need to store a value in a `const`, `var`, or `let`. Cypress recommends doing this only when dealing with mutable objects (that change state). - -For examples how to do this, please read our {% url 'Variables and Aliases guide' variables-and-aliases %}. - -## {% 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 within a {% url "`.then()`" then %} command. - -```javascript -cy.get('button').then(($el) => { - $el.get(0) -}) -``` - -## {% fa fa-angle-right %} How do I do something different if an element doesn't exist? - -What you're asking about is conditional testing and control flow. - -Please read our extensive {% url 'Conditional Testing Guide' conditional-testing %} which explains this in detail. - -## {% fa fa-angle-right %} How can I make Cypress wait until something is visible in the DOM? - -{% note info Remember %} -DOM based commands will automatically {% url "retry" retry-ability %} and wait for their corresponding elements to exist before failing. -{% endnote %} - -Cypress offers you many robust ways to {% url 'query the DOM' introduction-to-cypress#Querying-Elements %}, all wrapped with retry-and-timeout logic. - -Other ways to wait for an element's presence in the DOM is through `timeouts`. Cypress commands have a default timeout of 4 seconds, however, most Cypress commands have {% url 'customizable timeout options' configuration#Timeouts %}. Timeouts can be configured globally or on a per-command basis. - -In {% url 'some cases' interacting-with-elements#Visibility %}, your DOM element will not be actionable. Cypress gives you a powerful {%url '`{force:true}`' interacting-with-elements#Forcing %} option you can pass to most action commands. - -**Please read** our {% url 'Core Concepts Introduction to Cypress' introduction-to-cypress %}. This is the single most important guide for understanding how to test with Cypress. - -## {% fa fa-angle-right %} How do I wait for my application to load? - -We have seen many different iterations of this question. The answers can be varied depending on how your application behaves and the circumstances under which you are testing it. Here are a few of the most common versions of this question. - -**_How do I know if my page is done loading?_** - -When you load your application using `cy.visit()`, Cypress will wait for the `load` event to fire. It is really this easy. The {% url '`cy.visit()`' visit#Usage %} command loads a remote page and does not resolve until all of the external resources complete their loading phase. Because we expect your applications to observe differing load times, this command's default timeout is set to 60000ms. If you visit an invalid url or a {% url 'second unique domain' web-security#Same-superdomain-per-test %}, Cypress will log a verbose yet friendly error message. - - -**_In CI, how do I make sure my server has started?_** - -We recommend these great modules for this use case: - -* {% url '`wait-on`' https://www.npmjs.com/package/wait-on %} -* {% url '`start-server-and-test`' https://github.com/bahmutov/start-server-and-test %} - -**_How can I wait for my requests to be complete?_** - -The prescribed way to do this is to use {% url '`cy.server()`' server#Syntax %}, define your routes using {% url '`cy.route()`' route#Syntax %}, create {% url '`aliases`' variables-and-aliases#Aliases %} for these routes prior to the visit, and _then_ you can explicitly tell Cypress which routes you want to wait on using {% url '`cy.wait()`' wait#Syntax %}. **There is no magical way to wait for all of your XHRs or Ajax requests.** Because of the asynchronous nature of these requests, Cypress cannot intuitively know to wait for them. You must define these routes and be able to unambiguously tell Cypress which requests you want to wait on. - -## {% fa fa-angle-right %} Can I test the HTML `` element? - -Yes, you sure can. While executing tests in the Test Runner, you can view the entire `window.document` object in your open console using {% url '`cy.document()`' document %}. You can even make assertions on the `` element. Check out this example. - -```html - - - - - - - Test the HEAD content - - - - - -``` - -```js -describe('The Document Metadata', () => { - beforeEach(() => { - cy.visit('/') - }) - - it('looks inside the head content using `cy.document()`', () => { - // this will yield the entire window.document object - // if you click on DOCUMENT from the command log, - // it will output the entire #document to the console - cy.document() - }) - - // or make assertions on any of the metadata in the head element - - it('looks inside tag', () => { - cy.get('head title') - .should('contain', 'Test the HEAD content') - }) - - it('looks inside <meta> tag for description', () => { - cy.get('head meta[name="description"]') - .should('have.attr', 'content', 'This description is so meta') - }) -}) -``` - -## {% fa fa-angle-right %} Can I check that a form's HTML form validation is shown when an input is invalid? - -You certainly can. - -```javascript -it('check validation message on invalid input', () => { - cy.get('input:invalid').should('have.length', 0) - cy.get('[type="email"]').type('not_an_email') - cy.get('[type="submit"]').click() - cy.get('input:invalid').should('have.length', 1) - cy.get('[type="email"]').then(($input) => { - expect($input[0].validationMessage).to.eq('I expect an email!') - }) -}) -``` - - -## {% fa fa-angle-right %} Can I throttle network speeds using Cypress? - -You can throttle your network connection by accessing your Developer Tools Network panel. Additionally, you can add your own custom presets by selecting **Custom > Add** from the Network Conditions drawer. - -We do not currently offer any options to simulate this during `cypress run`. - -## {% fa fa-angle-right %} Can I use the new ES7 async / await syntax? - -No. The Command API is not designed in a way that makes this possible. This is not a limitation of Cypress - it is a very conscious and important design decision. - -Async / await is sugar around promises and Cypress commands are a mixture of both promises and streams. - -If you're curious please read: - -- Our {% url 'Introduction to Cypress guide' introduction-to-cypress#Commands-Are-Asynchronous %} which explains how the Commands are designed -- Our {% url 'Variables and Aliases guide' variables-and-aliases %} which talks about patterns dealing with async code - -## {% fa fa-angle-right %} How do I select or query for elements if my application uses dynamic classes or dynamic IDs? - -Easy - you don't use classes or ID's. You add `data-*` attributes to your elements and target them that way. - -Read more about the {% url 'best practices for selecting elements here' best-practices#Selecting-Elements %}. - -## {% fa fa-angle-right %} I want to run tests only within one specific folder. How do I do this? - -You can specify which test files to run during {% url "`cypress run`" command-line#cypress-run %} by {% url "passing a glob to the `--spec` flag" command-line#cypress-run-spec-lt-spec-gt %} matching the files you want to run. You should be able to pass a glob matching the specific folder where the tests are you want to run. - -This feature is not available when using {% url "`cypress open`" command-line#cypress-open %} however. - -## {% fa fa-angle-right %} Is there a suggested way or best practice for how I should target elements or write element selectors? - -Yes. Read more about the {% url 'best practices for selecting elements here' best-practices#Selecting-Elements %}. - -## {% fa fa-angle-right %} Can I prevent Cypress from failing my test when my application throws an uncaught exception error? - -Yes. - -By default Cypress will automatically fail tests whenever an uncaught exception bubbles up out of your app. - -Cypress exposes an event for this (amongst many others) that you can listen for to either: - -- Debug the error instance itself -- Prevent Cypress from failing the test - -This is documented in detail on the {% url "Catalog Of Events" catalog-of-events %} page. - -## {% fa fa-angle-right %} Can I override environment variables or create configuration for different environments? - -Yes, you can pass configuration to Cypress via environment variables, CLI arguments, JSON files and other means. - -{% url "Read the Environment Variables guide." environment-variables %} - -## {% fa fa-angle-right %} Can I override or change the default user agent the browser uses? - -Yes. {% url "You can override this with `userAgent` in `cypress.json`." configuration#Browser %} - -## {% fa fa-angle-right %} Can I block traffic going to specific domains? I want to block Google Analytics or other providers. - -Yes. {% url "You can set this with `blacklistHosts` in `cypress.json`." configuration#Browser %} - -Also, check out our {% url 'Stubbing Google Analytics Recipe' recipes#Stubbing-and-spying %}. - -## {% fa fa-angle-right %} How can I verify that calls to analytics like Google Analytics are being made correct? - -You can stub their functions and then ensure they're being called. - -Check out our {% url 'Stubbing Google Analytics Recipe' recipes#Stubbing-and-spying %}. - -## {% fa fa-angle-right %} I'm trying to test a chat application. Can I run more than one browser at a time with Cypress? - -{% url "We've answered this question in detail here." trade-offs#Multiple-browsers-open-at-the-same-time %} - -## {% fa fa-angle-right %} Can I test a chrome extension? How do I load my chrome extension? - -Yes. You can test your extensions by {% url 'loading them when we launch the browser.' browser-launch-api %}. - -## {% fa fa-angle-right %} How can I modify or pass arguments used to launch the browser? - -You use the {% url `before:browser:launch` browser-launch-api %} plugin event. - -## {% fa fa-angle-right %} Can I make cy.request() poll until a condition is met? - -Yes. You do it the {% url 'same way as any other recursive loop' request#Request-Polling %}. - -## {% fa fa-angle-right %} Can I use the Page Object pattern? - -Yes. - -The page object pattern isn't actually anything "special". If you're coming from Selenium you may be accustomed to creating instances of classes, but this is completely unnecessary and irrelevant. - -The "Page Object Pattern" should really be renamed to: "Using functions and creating custom commands". - -If you're looking to abstract behavior or roll up a series of actions you can create reusable {% url 'Custom Commands with our API' custom-commands %}. You can also just use regular ol' JavaScript functions without any of the ceremony typical with "Page Objects". - -For those wanting to use page objects, we've highlighted the {% url 'best practices ' custom-commands#Best-Practices %} for replicating the page object pattern. - -## {% fa fa-angle-right %} How can I parallelize my runs? - -You can read more about parallelization {% issue 64 'here' %}. - -## {% fa fa-angle-right %} Is Cypress compatible with Sauce Labs and BrowserStack? - -Our goal is to offer full integration with Sauce Labs and BrowserStack in the future, however, complete integration is not yet available. - -## {% 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 {% url `.only` writing-and-organizing-tests#Excluding-and-Including-Tests %} on a test suite or specific test. - -You can run a single test file or group of tests by passing the `--spec` flag to {% url '`cypress run`' command-line#cypress-run %}. - -## {% fa fa-angle-right %} How do I test uploading a file? - -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? - -The `projectId` is a 6 character string that helps identify your project once you've {% url "set up your tests to record" runs %}. It's generated by Cypress and typically is found in your {% url `cypress.json` configuration %} file. - -```json -{ - "projectId": "a7bq2k" -} -``` - -For further detail see the {% url Identification projects#Identification %} section of the {% url "Dashboard Service" dashboard-introduction%} docs. - -## {% fa fa-angle-right %} What is a Record Key? - -A *Record Key* is a GUID that's generated automatically by Cypress once you've {% url "set up your tests to record" runs %}. It helps identify your project and authenticate that your project is even *allowed* to record tests. - -You can find your project's record key inside of the *Settings* tab in the Test Runner. - -{% imgTag /img/dashboard/record-key-shown-in-desktop-gui-configuration.png "Record Key in Configuration Tab" %} - -For further detail see the {% url Identification projects#Identification %} section of the {% url "Dashboard Service" dashboard-introduction%} docs. - -## {% fa fa-angle-right %} How do I check that an email was sent out? - -{% note warning 'Anti-Pattern' %} -Don't try to use your UI to check email. Instead opt to programmatically use 3rd party APIs or talk directly to your server. Read about this {% url 'best practice' best-practices#Visiting-external-sites %} here. -{% endnote %} - -## {% 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 {% 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() -cy.route('users').as('getUsers') -cy.wait('@getUsers') // Wait for first GET to /users/ -cy.get('#list>li').should('have.length', 10) -cy.get('#load-more-btn').click() -cy.wait('@getUsers') // Wait for second GET to /users/ -cy.get('#list>li').should('have.length', 20) -``` - -## {% fa fa-angle-right %} How do I seed / reset my database? - -You can use {% url `cy.request()` request %}, {% url `cy.exec()` exec %}, or {% url `cy.task()` task %} to talk to your back end to seed data. - -You could also just stub XHR requests directly using {% url `cy.route()` route %} which avoids ever even needing to fuss with your database. - -## {% fa fa-angle-right %} How do I test elements inside an iframe? - -As of {% issue 136#issuecomment-328100955 `0.20.0` %} you can now wrap the elements of an iframe and work with them. - -We have an {% issue 685 'open proposal' %} to expand the APIs to support "switching into" an iframe and then back out of them. - -## {% fa fa-angle-right %} How do I preserve cookies / localStorage in between my tests? - -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 using the {% url "Cypress.Cookies api" cookies %}: - -```javascript -// now any cookie with the name 'session_id' will -// not be cleared before each test runs -Cypress.Cookies.defaults({ - whitelist: 'session_id' -}) -``` - -You **cannot** currently preserve localStorage across tests and can read more {% issue '461#issuecomment-325402086' '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 {% url "`.should('be.visible')`" should %} or {% url "another assertion" introduction-to-cypress#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') -``` - -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 exist - .should('be.visible') // and to be visible - -cy.get('.element').click({ timeout: 10000 }).should('not.have.class', 'animating') -// wait up to 10 seconds for the .element to not have 'animating' class -``` - -However, most of the time you don't even have to worry about animations. Why not? Cypress will {% url "automatically wait" interacting-with-elements %} for elements to stop animating prior to interacting with them via action commands like `.click()` or `.type()`. - -## {% 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 this behavior in your application. - -{% url 'Read through the recipe on tab handling and links to see how to test anchor links.' recipes#Testing-the-DOM %} - -## {% fa fa-angle-right %} Can I dynamically test multiple viewports? - -Yes, you can. We provide an {% url 'example here' viewport#Width-Height %}. - -## {% fa fa-angle-right %} Can I run the same tests on multiple subdomains? - -Yes. In this example, we loop through an array of urls and make assertions on the logo. - -```javascript -const urls = ['https://docs.cypress.io', 'https://www.cypress.io'] - -describe('Logo', () => { - urls.forEach((url) => { - it(`Should display logo on ${url}`, () => { - cy.visit(url) - cy.get('#logo img') - .should('have.attr', 'src') - .and('include', 'logo') - }) - }) -}) -``` - -{% imgTag /img/faq/questions/command-log-of-dynamic-url-test.png "Command Log multiple urls" %} - -## {% fa fa-angle-right %} How do I require or import node modules 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 a browser. - -You can `require` or `import` them as you're accustomed to. We preprocess your spec files with `babel` and `browserify`. - -Cypress does not have direct access to Node or your file system. We recommend utilizing one of the following to execute code outside of the browser: - -- {% url `cy.task()` task %} to run code in Node via the {% url "`pluginsFile`" configuration#Folders-Files %} -- {% url `cy.exec()` exec %} to execute a shell command - -{% url 'Check out the "Node Modules" example recipe.' recipes#Fundamentals %} - -## {% fa fa-angle-right %} Is there a way to give a proper SSL certificate to your proxy so the page doesn't show up as "not secure"? - -No, Cypress modifies network traffic in real time and therefore must sit between your server and the browser. There is no other way for us to achieve that. - -## {% fa fa-angle-right %} Is there any way to detect if my app is running under Cypress? - -You can check for the existence of `window.Cypress`, in your **application code**. - -Here's a simple example: - -```javascript -if (window.Cypress) { - // we are running in Cypress - // so do something different here - window.env = 'test' -} else { - // we are running in a regular ol' browser -} -``` - -## {% fa fa-angle-right %} Do you allow before, beforeEach, after, or afterEach hooks? - -Yes. You can read more {% url "here" writing-and-organizing-tests#Hooks %}. - -## {% fa fa-angle-right %} I tried to install Cypress in my CI, but I get the error: `EACCES: permission denied`. - -First, make sure you have {% url "Node" https://nodejs.org %} installed on your system. `npm` is a Node package that is installed globally by default when you install Node and is required to install our {% url "`cypress` npm package" command-line %}. - -Next, you'd want to check that you have the proper permissions for installing on your system or you may need to run `sudo npm install cypress`. - -## {% fa fa-angle-right %} Is there a way to test that a file got downloaded? I want to test that a button click triggers a download. - -There are a lot of ways to test this, so it depends. You'll need to be aware of what actually causes the download, then think of a way to test that mechanism. - -If your server sends specific disposition headers which cause a browser to prompt for download, you can figure out what URL this request is made to, and use {% url "cy.request()" request %} to hit that directly. Then you can test that the server send the right response headers. - -If it's just an anchor that initiates the download, you could just test that it has the right `href` property. As long as you can verify that clicking the button is going to make the right HTTP request, there's nothing else to test for. - -In the end, it's up to you to know your implementation and to test just enough to cover everything. - -## {% fa fa-angle-right %} Is it possible to catch the promise chain in Cypress? - -No. You cannot add a `.catch` error handler to a failed command. {% url "Read more about how the Cypress commands are not Promises" introduction-to-cypress#Commands-Are-Not-Promises %} - -## {% fa fa-angle-right %} Is there a way to modify the screenshots/video resolution? - -Not at the moment. {% issue 587 "There is an open issue for this." %} - -## {% fa fa-angle-right %} Does Cypress support ES7? - -Yes. You can customize how specs are processed by using one of our {% url 'preprocessor plugins' plugins %} or by {% url 'writing your own custom preprocessor' preprocessors-api %}. - -Typically you'd reuse your existing `babel`, `webpack`, `typescript` configurations. - -## {% fa fa-angle-right %} How does one determine what the latest version of Cypress is? - -There are a few ways. - -- The easiest way is probably to check our {% url "changelog" changelog %}. -- You can also check the latest version {% url "here" https://download.cypress.io/desktop.json %}. -- It's also always in our {% url "repo" https://github.com/cypress-io/cypress %}. - -## {% fa fa-angle-right %} Is there an ESLint plugin for Cypress or a list of globals? - -Yes! Check out our {% url "ESLint plugin" https://github.com/cypress-io/eslint-plugin-cypress %}. It will set up all the globals you need for running Cypress, including browser globals and {% url "Mocha" https://mochajs.org/ %} globals. - -## {% fa fa-angle-right %} When I visit my site directly, the certificate is verified, however the browser launched through Cypress is showing it as "Not Secure". Why? - -This is normal. Cypress modifies the traffic between your server and the browser. The browser notices this and displays a certificate warning. However, this is purely cosmetic and does not alter the way your application under test runs in any way, so you can safely ignore this warning. - -## {% fa fa-angle-right %} Is there an option to run Cypress in CI with Developer Tools open? We want to track network and console issues. - -No. This is definitely the motivation behind {% issue 448 "this open issue" %}, but there is not a way to run Cypress in `cypress run` with Developer Tools open. - -You may try running the tests locally and {% url "select the Electron browser" launching-browsers#Electron-Browser %}, that is as close as you will get with Developer Tools open and replicating the environment that was run during `cypress run`. - -## {% fa fa-angle-right %} How do I run the server and tests together and then shutdown the server? - -To start the server, run the tests and then shutdown the server we recommend {% url "these npm tools" continuous-integration#Boot-your-server %}. - -## {% fa fa-angle-right %} Can I test my Electron app? - -Testing your Electron app will not 'just work', as Cypress is designed to test anything that runs in a browser and Electron is a browser + Node. - -That being said, we use Cypress to test our own Desktop app's front end - by stubbing events from Electron. These tests are open source so you can check them out {% url "here" https://github.com/cypress-io/cypress/tree/develop/packages/desktop-gui/cypress/integration %}. - -## {% fa fa-angle-right %} I found a bug! What do I do? - -- Search existing {% url "open issues" https://github.com/cypress-io/cypress/issues %}, it may already be reported! -- Update Cypress. Your issue may have {% url "already been fixed" changelog %}. -- {% open_an_issue %}. Your best chance of getting a bug looked at quickly is to provide a repository with a reproducible bug that can be cloned and run. - -## {% fa fa-angle-right %} What are your best practices for organizing tests? - -We see organizations _starting_ with Cypress by placing end-to-end tests in a separate repo. This is a great practice that allows someone on the team to prototype a few tests and evaluate Cypress within minutes. As the time passes and the number of tests grows, we _strongly suggest_ moving end-to-end tests to live right alongside your front end code. This brings many benefits: - -- engages developers in writing end-to-end tests sooner -- keeps tests and the features they tests in sync -- tests can be run every time the code changes -- allows code sharing between the application code and the tests (like selectors) - -## {% fa fa-angle-right %} What is the right balance between custom commands and utility functions? - -There is already a great section in {% url "Custom Commands" custom-commands#Best-Practices %} guide that talks about trade-offs between custom commands and utility functions. We feel reusable functions in general are a way to go. Plus they do not confuse {% issue 1065 'IntelliSense like custom commands do' %}. - -## {% fa fa-angle-right %} Can I print the list of commands from a test in the terminal? - -If a test fails, Cypress takes a screenshot image, but does not print the list of commands in the terminal, only the failed assertion. There is a user space plugin {% url cypress-failed-log https://github.com/bahmutov/cypress-failed-log %} that saves a JSON file with all commands from a failed test. We are also working on mirroring `console.log` messages from the browser in the terminal, see {% issue 2078 %}. - -## {% fa fa-angle-right %} Can my tests interact with Redux / Vuex data store? - -Usually your end-to-end tests interact with the application through public browser APIs: DOM, network, storage, etc. But sometimes you might want to assert the data held inside the application's data store. Cypress makes it simple. Tests run right in the same browser instance and can reach into the application's context using {% url `cy.window` window %}. By conditionally exposing the application reference and data store from the application's code, you can allow the tests to make assertions about the data store, and even drive the application via Redux actions. - -- see {% url "Testing Redux Store" https://www.cypress.io/blog/2018/11/14/testing-redux-store/ %} blog post and {% url "Redux Testing" recipes#Blogs %} recipe. -- see {% url "Testing Vue web applications with Vuex data store & REST back end" https://www.cypress.io/blog/2017/11/28/testing-vue-web-application-with-vuex-data-store-and-rest-backend/ %} blog post and {% url 'Vue + Vuex + REST Testing' recipes#Blogs %} recipe. diff --git a/source/zh-cn/guides/guides/debugging.md b/source/zh-cn/guides/guides/debugging.md deleted file mode 100644 index ecf0abc239..0000000000 --- a/source/zh-cn/guides/guides/debugging.md +++ /dev/null @@ -1,426 +0,0 @@ ---- -title: 调试 ---- - -{% note info %} -# {% fa fa-graduation-cap %} 通过这篇文档你将会学习到 - -- Cypress如何在同一个事件循环中运行你的代码, 并且保持调试简单易懂 -- Cypress如何接受标准的开发工具 -- 如何以及何时使用`调试工具`已经{% url `.debug()` debug %}速记命令 -- 如何解决Cypress本身的问题 -{% endnote %} - -# 使用`调试器` - -你的Cypress测试代码运行在与应用程序相同的运行循环中.这意味着你可以访问页面上运行的代码, 以及浏览器为你提供的东西, 比如`document`, `window`等等, 当然也包括`调试器`. - -## 像往常一样调试 - -基于这些陈述, 你可能想在测试中添加一个`调试器`, 就像这样: - -```js -it('let me debug like a fiend', function() { - cy.visit('/my/page/path') - - cy.get('.selector-in-question') - - debugger // Doesn't work -}) -``` - -This may not work exactly as you are expecting. As you may remember from the {% url "Introduction to Cypress" introduction-to-cypress %}, `cy` commands enqueue an action to be taken later. Can you see what the test above will do given that perspective? - -Both {% url `cy.visit()` visit %} and {% url `cy.get()` get %} will return immediately, having enqueued their work to be done later, and `debugger` will be executed before any of the commands have actually run. - -Let's use {% url `.then()` then %} to tap into the Cypress command during execution and add a `debugger` at the appropriate time: - -```js -it('let me debug when the after the command executes', function () { - cy.visit('/my/page/path') - - cy.get('.selector-in-question') - .then(($selectedElement) => { - // Debugger is hit after the cy.visit - // and cy.get command have completed - debugger - }) -}) -``` - -Now we're in business! The first time through, {% url `cy.visit()` visit %} and the {% url `cy.get()` get %} chain (with its {% url `.then()` then %} attached) are enqueued for Cypress to execute. The `it` block exits, and Cypress starts its work: - -1. The page is visited, and Cypress waits for it to load. -2. The element is queried, and Cypress automatically waits and retries for a few moments if it isn't found immediately. -3. The function passed to {% url `.then()` then %} is executed, with the found element yielded to it. -4. Within the context of the {% url `.then()` then %} function, the `debugger` is called, halting the browser and calling focus to the Developer Tools. -5. You're in! Inspect the state of your application like you normally would if you'd dropped the `debugger` into your application code. - -## Using {% url `.debug()` debug %} - -Cypress also exposes a shortcut for debugging commands, {% url `.debug()` debug %}. Let's rewrite the test above using this helper method: - -```js -it('let me debug like a fiend', function() { - cy.visit('/my/page/path') - - cy.get('.selector-in-question') - .debug() -}) -``` - -The current subject that is yielded by the {% url `cy.get()` get %} is exposed as the variable `subject` within your Developer Tools so that you can interact with it in the console. - -{% imgTag /img/guides/debugging-subject.png "Debugging Subject" %} - -Use {% url `.debug()` debug %} to quickly inspect any (or many!) part(s) of your application during the test. You can attach it to any Cypress chain of commands to have a look at the system's state at that moment. - -# Using the Developer Tools - -Though Cypress has built out {% url "an excellent Test Runner" test-runner %} to help you understand what is happening in your application and your tests, there's no replacing all the amazing work browser teams have done on their built-in development tools. Once again, we see that Cypress goes _with_ the flow of the modern ecosystem, opting to leverage these tools wherever possible. - -{% note info %} -## {% fa fa-video-camera %} See it in action! - -You can see a walk-through of debugging some application code from Cypress {% url "in this segment from our React tutorial series" https://vimeo.com/242961930#t=264s %}. -{% endnote %} - -## Get console logs for commands - -All of Cypress's commands, when clicked on within the {% url "Command Log" test-runner#Command-Log %}, print extra information about the command, its subject, and its yielded result. Try clicking around the Command Log with your Developer Tools open! You may find some useful information here. - -### When clicking on `.type()` command, the Developer Tools console outputs the following: - -{% imgTag /img/api/type/console-log-of-typing-with-entire-key-events-table-for-each-character.png "Console Log type" %} - -# Troubleshooting Cypress - -There are times when you will encounter errors or unexpected behavior with Cypress itself. In this situation, we recommend checking these support resources **first**. - -## Support channels - -- Connect with our community in {% url "Gitter" https://gitter.im/cypress-io/cypress %} -- Search existing {% url "GitHub issues" https://github.com/cypress-io/cypress/issues %} -- Search this documentation (search is in the top right) 😉 -- Search {% url "Stack Overflow" https://stackoverflow.com/questions/tagged/cypress %} for relevant answers -- If your organization signs up for one of our {% url "paid plans" https://www.cypress.io/pricing/ %}, you can get dedicated email support, which gives you one-on-one help from our team. -- If you still haven't found a solution, {% url "open an issue" https://github.com/cypress-io/cypress/issues/new %} *with a reproducible example*. - -## Isolate the Problem - -When debugging a failing test, follow these general principles to isolate the problem: - -- Look at the {% url "video recordings and screenshots" screenshots-and-videos %}. -- Split large spec files into smaller ones. -- Split long tests into smaller tests. -- Run the same test using {% url '`--browser chrome`' command-line#cypress-run-browser-lt-browser-name-or-path-gt %}. The problem might be isolated to the Electron browser. -- If isolated to the Electron browser. Run the same tests in both Electron and Chrome, then compare the screenshots/videos. Look for and isolate any differences in the Command Log. - -{% partial chromium_download %} - -## Clear Cypress cache - -If you're having an issue during installation of Cypress, try removing the contents of the Cypress cache. - -This will clear out all installed versions of Cypress that may be cached on your machine. - -```shell -cypress cache clear -``` - -After running this command, you will need to run `cypress install` before running Cypress again. - -```shell -npm install cypress --save-dev -``` - -## Launching browsers - -Cypress attempts to {% url 'automatically find installed Chrome versions for you' launching-browsers %}. However, probing for browsers across different environments can be error-prone. If Cypress cannot find a browser but you know you have it installed, there are ways to ensure that Cypress can "see" it. - -{% note info Using the `--browser` command line argument %} -You can also supply the `--browser` command line argument to launch a browser from a known filesystem path to bypass browser auto detection. {% url "See 'Launching Browsers' for more information" launching-browsers#Launching-by-a-path % } %} -{% endnote %} - -To see debug logs from the browser launcher, run Cypress with the `DEBUG` environment variable set to `cypress:launcher`. - -### Mac - -On Mac, Cypress attempts to find installed browsers by their bundle identifier. If this does not succeed, it will fall back to the Linux browser detection method. - -Browser Name | Expected Bundle Identifier | Expected Executable ---- | --- | --- -`chrome` | `com.google.Chrome` | `Contents/MacOS/Google Chrome` -`chromium` | `org.chromium.Chromium` | `Contents/MacOS/Chromium` -`canary` | `com.google.Chrome.canary` | `Contents/MacOS/Google Chrome Canary` - -### Linux - -On Linux, Cypress scans your `PATH` for a number of different binary names. If the browser you are trying to use does not exist under one of the expected binary names, Cypress will not be able to find it. - -Browser Name | Expected Binary Name(s) ---- | --- -`chrome` | `google-chrome`, `chrome`, or `google-chrome-stable` -`chromium` | `chromium-browser` or `chromium` -`canary` | `google-chrome-canary` - -These binary names should work for most Linux distributions. If your distribution packages browsers under a different binary name, you can add a symlink using the expected binary name so that Cypress can detect it. - -For example, if your distribution packages Google Chrome as `chrome`, you could add a symlink to `google-chrome` like this: - -```shell -sudo ln `which chrome` /usr/local/bin/google-chrome -``` - -### Windows - -On Windows, Cypress scans the following locations to try to find each browser: - -Browser Name | Expected Path ---- | --- -`chrome` | `C:/Program Files (x86)/Google/Chrome/Application/chrome.exe` -`chromium` | `C:/Program Files (x86)/Google/chrome-win32/chrome.exe` -`canary` | `%APPDATA%/../Local/Google/Chrome SxS/Application/chrome.exe` - -To make a browser installed at a different path be auto-detected, create a symbolic link using `mklink` in the location that Cypress expects to find your browser. - -{% url 'Read more about creating symbolic links on Windows' https://www.howtogeek.com/howto/16226/complete-guide-to-symbolic-links-symlinks-on-windows-or-linux/ %} - -## Chrome extension whitelisting - -Cypress utilizes a Chrome extension within the Test Runner in order to run properly. If you or your company whitelist specific Chrome extensions, this may cause problems with running Cypress. You will want to ask your administrator to whitelist the Cypress extension ID below: - -```sh -caljajdfkjjjdehjdoimjkkakekklcck -``` - -## Clear App Data - -Cypress maintains some local application data in order to save user preferences and more quickly start up. Sometimes this data can become corrupted. You may fix an issue you have by clearing this app data. - -### To clear App Data - -1. Open Cypress via `cypress open` -2. Go to `File` -> `View App Data` -3. This will take you to the directory in your file system where your App Data is stored. If you cannot open Cypress, search your file system for a directory named `cy` whose content should look something like this: - - ```text - 📂 production - 📄 all.log - 📁 browsers - 📁 bundles - 📄 cache - 📁 projects - 📁 proxy - 📄 state.json - ``` -4. Delete everything in the `cy` folder -5. Close Cypress and open it up again - -## Step through test commands - -You can run the test command by command using the {% url `.pause()` pause %} command. - -```javascript -it('adds items', function () { - cy.pause() - cy.get('.new-todo') - // more commands -}) -``` - -This allows you to inspect the web application, the DOM, the network, and any storage after each command to make sure everything happens as expected. - -## Print DEBUG logs - -Cypress is built using the {% url 'debug' https://github.com/visionmedia/debug %} module. That means you can receive helpful debugging output by running Cypress with this turned on. **Note:** you will see a LOT of messages when running with `DEBUG=...` setting. - -**On Mac or Linux:** - -```shell -DEBUG=cypress:* cypress open -``` - -**On Windows:** - -```shell -set DEBUG=cypress:* -``` - -```shell -cypress open -``` - -Read more {% url 'about the CLI options here' command-line#Debugging-commands %} and {% url "Good Logging" https://glebbahmutov.com/blog/good-logging/ %} blog post. - -### Detailed Logs - -There are several levels of `DEBUG` messages - -```shell -# prints very few top-level messages -DEBUG=cypress:server ... -# prints ALL messages from server package -DEBUG=cypress:server* ... -# prints messages only from config parsing -DEBUG=cypress:server:config ... -``` - -This allows you to isolate the problem a little better - -### Debug logs in the browser - -If the problem is seen during `cypress open` you can print debug logs in the browser too. Open the browser's Developer Tools and set a `localStorage` property: - -```javascript -localStorage.debug = 'cypress*' - -// to disable debug messages -delete localStorage.debug -``` - -Reload the browser and see debug messages within the Developer Tools console. You will only see the "cypress:driver" package logs that run in the browser, as you can see below. - -{% imgTag /img/api/debug/debug-driver.jpg "Debug logs in browser" %} - -## Log Cypress events - -In addition to the `DEBUG` messages, Cypress also emits multiple events you can listen to as shown below. {% url 'Read more about logging events in the browser here' catalog-of-events#Logging-All-Events %}. - -{% imgTag /img/api/catalog-of-events/console-log-events-debug.png "console log events for debugging" %} - -## Run Cypress command outside the test - -If you need to run a Cypress command straight from the Developer Tools console, you can use the internal command `cy.now('command name', ...arguments)`. For example, to run the equivalent of `cy.task('database', 123)` outside the normal execution command chain: - -```javascript -cy.now('task', 123) - .then(console.log) -// runs cy.task(123) and prints the resolved value -``` - -{% note warning %} -The `cy.now()` command is an internal command and may change in the future. -{% endnote %} - -## Additional information - -### Write command log to the terminal - -You can include the plugin [cypress-failed-log](https://github.com/bahmutov/cypress-failed-log) in your tests. This plugin writes the list of Cypress commands to the terminal as well as a JSON file if a test fails. - -{% imgTag /img/api/debug/failed-log.png "cypress-failed-log terminal output" %} - -# Hacking on Cypress - -If you want to dive into Cypress and edit the code yourself, you can do that. The Cypress code is open source and licensed under an {% url "MIT license" https://github.com/cypress-io/cypress/blob/develop/LICENSE %}. There are a few tips on getting started that we've outlined below. - -## Contribute - -If you'd like to contribute directly to the Cypress code, we'd love to have your help! Please check out our {% url "contributing guide" https://github.com/cypress-io/cypress/blob/develop/CONTRIBUTING.md %} to learn about the many ways you can contribute. - -## Run the Cypress app by itself - -Cypress comes with an npm CLI module that parses the arguments, starts the Xvfb server (if necessary), and then opens the Test Runner application built on top of {% url "Electron" https://electronjs.org/ %}. Some common situations on why you would want to do this are: - -- debug Cypress not starting or hanging -- debug problems related to the way CLI arguments are parsed by the npm CLI module - -Here is how you can launch Cypress application directly without the npm CLI module. First, find where the binary is installed using the {% url "`cypress cache path`" command-line#cypress-cache-path %} command. - -For example, on a Linux machine: - -```shell -npx cypress cache path -/root/.cache/Cypress -``` - -Second, try a smoke test that verifies that the application has all its required dependencies present on the host machine: - -```shell -/root/.cache/Cypress/3.3.1/Cypress/Cypress --smoke-test --ping=101 -101 -``` - -If there is a missing dependency, the application should print an error message. You can see the Electron verbose log messages by setting an {% url "environment variable ELECTRON_ENABLE_LOGGING" https://electronjs.org/docs/api/environment-variables %}: - -```shell -ELECTRON_ENABLE_LOGGING=true DISPLAY=10.130.4.201:0 /root/.cache/Cypress/3.3.1/Cypress/Cypress --smoke-test --ping=101 -[809:0617/151243.281369:ERROR:bus.cc(395)] Failed to connect to the bus: Failed to connect to socket /var/run/dbus/system_bus_socket: No such file or directory -101 -``` - -If the smoke test fails to execute, check if a shared library is missing (a common problem on Linux machines without all of the Cypress dependencies present). - -```shell -ldd /home/person/.cache/Cypress/3.3.1/Cypress/Cypress - linux-vdso.so.1 (0x00007ffe9eda0000) - libnode.so => /home/person/.cache/Cypress/3.3.1/Cypress/libnode.so (0x00007fecb43c8000) - libpthread.so.0 => /lib/x86_64-linux-gnu/libpthread.so.0 (0x00007fecb41ab000) - libgtk-3.so.0 => not found - libgdk-3.so.0 => not found - ... -``` - -**Tip:** use {% url "Cypress Docker image" docker %} or install dependencies by copying them from one of our official Docker images. - -**Note:** verbose Electron logging might show warnings that still allow Cypress to work normally. For example, the Cypress Test Runner opens normally despite the scary output below: - -```shell -ELECTRON_ENABLE_LOGGING=true DISPLAY=10.130.4.201:0 /root/.cache/Cypress/3.3.1/Cypress/Cypress -[475:0617/150421.326986:ERROR:bus.cc(395)] Failed to connect to the bus: Failed to connect to socket /var/run/dbus/system_bus_socket: No such file or directory -[475:0617/150425.061526:ERROR:bus.cc(395)] Failed to connect to the bus: Could not parse server address: Unknown address type (examples of valid types are "tcp" and on UNIX "unix") -[475:0617/150425.079819:ERROR:bus.cc(395)] Failed to connect to the bus: Could not parse server address: Unknown address type (examples of valid types are "tcp" and on UNIX "unix") -[475:0617/150425.371013:INFO:CONSOLE(73292)] "%cDownload the React DevTools for a better development experience: https://fb.me/react-devtools -You might need to use a local HTTP server (instead of file://): https://fb.me/react-devtools-faq", source: file:///root/.cache/Cypress/3.3.1/Cypress/resources/app/packages/desktop-gui/dist/app.js (73292) -``` - -You can also see verbose Cypress logs when running the Test Runner binary - -```shell -DEBUG=cypress* DISPLAY=10.130.4.201:0 /root/.cache/Cypress/3.3.1/Cypress/Cypress --smoke-test --ping=101 -cypress:ts Running without ts-node hook in environment "production" +0ms -cypress:server:cypress starting cypress with argv [ '/root/.cache/Cypress/3.3.1/Cypress/Cypress', '--smoke-test', '--ping=101' ] +0ms -cypress:server:args argv array: [ '/root/.cache/Cypress/3.3.1/Cypress/Cypress', '--smoke-test', '--ping=101' ] +0ms -cypress:server:args argv parsed: { _: [ '/root/.cache/Cypress/3.3.1/Cypress/Cypress' ], smokeTest: true, ping: 101, cwd: '/root/.cache/Cypress/3.3.1/Cypress/resources/app/packages/server' } +7ms -cypress:server:args options { _: [ '/root/.cache/Cypress/3.3.1/Cypress/Cypress' ], smokeTest: true, ping: 101, cwd: '/root/.cache/Cypress/3.3.1/Cypress/resources/app/packages/server', config: {} } +2ms -cypress:server:args argv options: { _: [ '/root/.cache/Cypress/3.3.1/Cypress/Cypress' ], smokeTest: true, ping: 101, cwd: '/root/.cache/Cypress/3.3.1/Cypress/resources/app/packages/server', config: {}, pong: 101 } +1ms -cypress:server:appdata path: /root/.config/Cypress/cy/production +0ms -cypress:server:cypress starting in mode smokeTest +356ms -101 -cypress:server:cypress about to exit with code 0 +4ms -``` - -## Edit the installed Cypress code - -The installed Test Runner comes with the fully transpiled, unobfuscated JavaScript source code that you can hack on. You might want to directly modify the installed Test Runner code to: - -- investigate a hard to recreate bug that happens on your machine -- change the run-time behavior of Cypress before opening a pull request -- have fun 🎉 - -First, print where the binary is installed using the {% url "`cypress cache path`" command-line#cypress-cache-path %} command. - -For example, on a Mac: - -```shell -npx cypress cache path -/Users/jane/Library/Caches/Cypress -``` - -Second, open the source code at the following path in any code editor. Make sure to substitute `3.3.1` for the desired version of the Test Runner you want to edit. - -```text -/Users/jane/Library/Caches/Cypress/3.3.1/Cypress.app/Contents/Resources/app/packages/ -``` - -You can change anything in the JavaScript code: - -{% imgTag /img/guides/source-code.png "Source code of the Test Runner in a text editor" %} - -When finished, if necessary, remove the edited Test Runner version and reinstall the Cypress official version to get back to the official released code. - -```shell -rm -rf /Users/jane/Library/Caches/Cypress/3.3.1 -npm install cypress@3.3.1 -```