diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 09607540e5..1438ecae1e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -104,9 +104,19 @@ To add a page such as a new guide or API documentation: - Link to your new page in the [`sidebar.yml`](/source/_data/sidebar.yml). - Add translations for the sidebar link for each supported language (for English, this is located in [`en.yml`](/themes/cypress/languages/en.yml)). - Build the documentation site locally so that you can visually inspect your new page and the links to it. -- Commit the new file using git - we auto-generate the doc to display within each supported language, this auto-generation depends on the file existing in git. +- **REQUIRED**: Commit the new file using git - we auto-generate the doc to display within each supported language, this auto-generation depends on the file existing in git. - Submit a [pull request](#Pull-Requests) for your change. +### Deleting Pages + +To delete a page: + +- Delete the page from the relevant directory under [`source`](/source). +- Remove the link from the the [`sidebar.yml`](/source/_data/sidebar.yml). +- Remove the translations for the sidebar link for each supported language (for English, this is located in [`en.yml`](/themes/cypress/languages/en.yml)). +- **REQUIRED**: Commit the change using git - we auto-remove the doc within each supported language, this auto-generation depends on the file being deleted in git, the build will not work until this is commited. +- Build the documentation site locally so that you can visually inspect and make sure it was properly deleted. + #### A Worked Example Let's imagine that the Cypress team has just added a new command called `privateState` and you've picked up the task to document it. diff --git a/source/_changelogs/3.4.0.md b/source/_changelogs/3.4.0.md index 93cea6cfaa..01e67a4201 100644 --- a/source/_changelogs/3.4.0.md +++ b/source/_changelogs/3.4.0.md @@ -24,7 +24,7 @@ - Environment variables for Semaphore 2.0 are now captured when recording tests to the Dashboard. Fixes {% issue 4671 %}. - We now capture environment variables set from Concourse CI when recording tests to the Dashboard. Fixes {% issue 4376 %}. - We replaced capturing environment variables from SnapCI (which is no longer available) to instead capture ones set from GoCD when recording tests to the Dashboard. Fixes {% issue 2680 %}. -- The {% url "JSON schema file" https://on.cypress.io/cypress.schema.json %} used for {% url "intelligent code completion" https://on.cypress.io/intelligent-code-completion#Configuration %} for the Cypress configuration file has been updated to match our documentation. +- The {% url "JSON schema file" https://on.cypress.io/cypress.schema.json %} used for {% url "intelligent code completion" IDE-integration#Intelligent-Code-Completion %} for the Cypress configuration file has been updated to match our documentation. **Documentation Changes:** diff --git a/source/_changelogs/4.0.0.md b/source/_changelogs/4.0.0.md index 9e7ff77481..d2efa5daf6 100644 --- a/source/_changelogs/4.0.0.md +++ b/source/_changelogs/4.0.0.md @@ -48,7 +48,7 @@ Cypress 4.0.0 includes support for {% url "Mozilla Firefox" https://www.mozilla. - The browser icons in the Test Runner now display as images with the proper branding. Addresses {% issue 6188 %}. - We updated the styling of browser dropdown in the Test Runner to look more like a button. Addresses {% issue 6298 %}. - The timer in the Test Runner now always displays at a consistent length. Addresses {% issue 6168 %}. -- You can print debug information about the memory & CPU usage of Cypress, which can be accessed by enabling the {% url "`cypress:server:util:process_profiler` debug stream" debugging#Log-memory-and-CPU-usage %}. Addresses {% issue 6169 %}. +- You can print debug information about the memory & CPU usage of Cypress, which can be accessed by enabling the {% url "`cypress:server:util:process_profiler` debug stream" troubleshooting#Log-memory-and-CPU-usage %}. Addresses {% issue 6169 %}. - We added types for plugin events. Addresses {% issue 6322 %}. **Dependency Updates** diff --git a/source/_data/sidebar.yml b/source/_data/sidebar.yml index ac40c485c7..893ee7b3b7 100644 --- a/source/_data/sidebar.yml +++ b/source/_data/sidebar.yml @@ -36,7 +36,7 @@ guides: cross-browser-testing: cross-browser-testing.html web-security: web-security.html tooling: - intelligent-code-completion: intelligent-code-completion.html + IDE-integration: IDE-integration.html plugins-guide: plugins-guide.html reporters: reporters.html typescript-support: typescript-support.html @@ -51,6 +51,7 @@ guides: error-messages: error-messages.html bundled-tools: bundled-tools.html trade-offs: trade-offs.html + troubleshooting: troubleshooting.html changelog: changelog.html migration-guide: migration-guide.html roadmap: roadmap.html diff --git a/source/guides/core-concepts/introduction-to-cypress.md b/source/guides/core-concepts/introduction-to-cypress.md index 2e7c6050f9..12891ba5d5 100644 --- a/source/guides/core-concepts/introduction-to-cypress.md +++ b/source/guides/core-concepts/introduction-to-cypress.md @@ -805,7 +805,8 @@ All DOM based commands automatically wait for their elements to exist in the DOM You don't need to write {% url "`.should('exist')`" should %} after a DOM based command, unless you chain extra `.should()` assertions. {% endnote %} -{% note danger "Negative DOM assertions" %} +#### Negative DOM assertions + If you chain any `.should()` command, the default `.should('exist')` is not asserted. This does not matter for most *positive* assertions, such as `.should('have.class')`, because those imply existence in the first place, but if you chain *negative* assertions ,such as `.should('not.have.class')`, they will pass even if the DOM element doesn't exist: ```js @@ -822,9 +823,6 @@ cy.get('.does-not-exist').should(($element) => { }) ``` -There's an {% url 'open discussion' https://github.com/cypress-io/cypress/issues/205 %} about this behavior. -{% endnote %} - These rules are pretty intuitive, and most commands give you the flexibility to override or bypass the default ways they can fail, typically by passing a `{force: true}` option. ### Example #1: Existence and Actionability diff --git a/source/guides/core-concepts/test-runner.md b/source/guides/core-concepts/test-runner.md index 847f232fd8..ec858b33ec 100644 --- a/source/guides/core-concepts/test-runner.md +++ b/source/guides/core-concepts/test-runner.md @@ -39,15 +39,15 @@ Each command, assertion, or error, when clicked on, displays extra information i For certain commands like {% url `cy.route()` route %}, {% url `cy.stub()` stub %}, and {% url `cy.spy()` spy %}, an extra instrument panel is displayed above the test to give more information about the state of your tests. -## Routes: +## Routes {% imgTag /img/guides/instrument-panel-routes.png "Routes Instrument Panel" %} -## Stubs: +## Stubs {% imgTag /img/guides/instrument-panel-stubs.png "Stubs Instrument Panel" %} -## Spies: +## Spies {% imgTag /img/guides/instrument-panel-spies.png "Spies Instrument Panel" %} diff --git a/source/guides/dashboard/projects.md b/source/guides/dashboard/projects.md index 2b9f808d1b..56a36dab02 100644 --- a/source/guides/dashboard/projects.md +++ b/source/guides/dashboard/projects.md @@ -73,7 +73,7 @@ If you're using source control, we recommend that you check your `cypress.json`, export CYPRESS_PROJECT_ID={projectId} ``` -## Record key {% fa fa-key %} +## Record key The record key is used to authenticate that your project is *allowed* to record tests to the Dashboard Service. As long as your record key stays *private*, nobody will be able to record test runs for your project - even if they have your `projectId`. diff --git a/source/guides/getting-started/writing-your-first-test.md b/source/guides/getting-started/writing-your-first-test.md index 19bd920eaf..8c88c337b8 100644 --- a/source/guides/getting-started/writing-your-first-test.md +++ b/source/guides/getting-started/writing-your-first-test.md @@ -219,7 +219,7 @@ Now we can assert something about this new page! {% video local /img/snippets/first-test-click-30fps.mp4 %} {% note info %} -{% fa fa-magic %} You can see IntelliSense in your spec files by adding a single special comment line. Read about {% url 'Intelligent Code Completion' intelligent-code-completion#Triple-slash-directives %}. +{% fa fa-magic %} You can see IntelliSense in your spec files by adding a single special comment line. Read about {% url 'Intelligent Code Completion' IDE-integration#Triple-slash-directives %}. {% endnote %} ## {% fa fa-check-square-o %} Step 4: Make an assertion @@ -229,8 +229,8 @@ Let's make an assertion about something on the new page we clicked into. Perhaps Here's what that looks like: ```js -describe('My First Test', function() { - it('clicking "type" navigates to a new url', function() { +describe('My First Test', () => { + it('clicking "type" navigates to a new url', () => { cy.visit('https://example.cypress.io') cy.contains('type').click() @@ -250,8 +250,8 @@ We can continue the interactions and assertions in this test by adding another c We can use {% url "`cy.get()`" get %} to select an element based on a CSS class. Then we can use the {% url "`.type()`" type %} command to enter text into the selected input. Finally, we can verify that the value of the input reflects the text that was typed with another {% url "`.should()`" should %}. ```js -describe('My First Test', function() { - it('Gets, types and asserts', function() { +describe('My First Test', () => { + it('Gets, types and asserts', () => { cy.visit('https://example.cypress.io') cy.contains('type').click() @@ -431,7 +431,7 @@ Now Cypress provides us a UI (similar to debugger) to step forward through each {% imgTag /img/guides/first-test-paused.png "Test Runner shows label saying 'Paused' with Command Log showing 'Pause'" %} -## In action +### In action {% video local /img/snippets/first-test-debugging-30fps.mp4 %} @@ -496,7 +496,7 @@ describe('My First Test', function() { # Next steps - Start {% url 'testing your app' testing-your-app %}. -- Set up {% url 'intelligent code completion' intelligent-code-completion %} for Cypress commands and assertions. +- Set up {% url 'intelligent code completion' IDE-integration#Intelligent-Code-Completion %} for Cypress commands and assertions. - Search Cypress's documentation to quickly find what you need. {% imgTag /img/guides/search-box.png "Use the search box to find relevant documentation" %} diff --git a/source/guides/guides/command-line.md b/source/guides/guides/command-line.md index 2621f475f2..422080ee4d 100644 --- a/source/guides/guides/command-line.md +++ b/source/guides/guides/command-line.md @@ -115,7 +115,7 @@ You can also choose a browser by supplying a path: cypress run --browser /usr/bin/chromium ``` -{% url "Having trouble with browser detection? Check out the debugging guide" debugging#Launching-browsers %} +{% url "Having trouble with browser detection? Check out our troubleshooting guide" troubleshooting#Launching-browsers %} ### `cypress run --ci-build-id ` @@ -371,7 +371,7 @@ If found, the specified browser will be added to the list of available browsers Currently, only browsers in the Chrome family are supported (including the new Chromium-based Microsoft Edge and Brave). -{% url "Having trouble launching a browser? Check out the debugging guide" debugging#Launching-browsers %} +{% url "Having trouble launching a browser? Check out our troubleshooting guide" troubleshooting#Launching-browsers %} ### `cypress open --config ` diff --git a/source/guides/guides/debugging.md b/source/guides/guides/debugging.md index 6cfc273cdc..b34511a565 100644 --- a/source/guides/guides/debugging.md +++ b/source/guides/guides/debugging.md @@ -8,7 +8,6 @@ title: Debugging - How Cypress runs in the same event loop with your code, keeping debugging less demanding and more understandable - How Cypress embraces the standard Developer Tools - How and when to use `debugger` and the shorthand {% url `.debug()` debug %} command -- How to troubleshoot issues with Cypress itself {% endnote %} # Using `debugger` @@ -75,159 +74,7 @@ The current subject that is yielded by the {% url `cy.get()` get %} is exposed a 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" %} - -# Cypress fiddle - -While learning Cypress it may be a good idea to try small tests against some HTML. We have written a {% url @cypress/fiddle https://github.com/cypress-io/cypress-fiddle %} plugin for this. It can quickly mount any given HTML and run some Cypress test commands against it. - -# 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 %} - -You can see the full list of found browsers and their properties within the {% url "resolved configuration" configuration#Resolved-Configuration %} in the **Settings** tab of the Test Runner. - -Another way to log what is found by Cypress is to run Cypress with the {% urlHash "DEBUG environment variable" Print-DEBUG-logs %} set to `cypress:launcher`. This will print information about the found browsers and their properties to the terminal. - -### 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` -`chrome:canary` | `com.google.Chrome.canary` | `Contents/MacOS/Google Chrome Canary` - -For the current list, see {% url 'packages/launcher' https://github.com/cypress-io/cypress/blob/develop/packages/launcher/lib/darwin/index.ts %} files. - -### 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` -`chrome: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` -`chrome:canary` | `%APPDATA%/../Local/Google/Chrome SxS/Application/chrome.exe` - -For the current list, see {% url 'packages/launcher' https://github.com/cypress-io/cypress/blob/develop/packages/launcher/lib/windows/index.ts %} files. - -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 +# Step through test commands You can run the test command by command using the {% url `.pause()` pause %} command. @@ -241,62 +88,31 @@ it('adds items', function () { 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 run -``` - -**On Windows:** - -```shell -set DEBUG=cypress:* -cypress run -``` - -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 ... -``` +# Using the Developer Tools -This allows you to isolate the problem a little better +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. -### Debug logs in the browser +{% note info %} +## {% fa fa-video-camera %} See it in action! -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: +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 %} -```javascript -localStorage.debug = 'cypress*' +## Get console logs for commands -// to disable debug messages -delete localStorage.debug -``` +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. -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. +### When clicking on `.type()` command, the Developer Tools console outputs the following: -{% imgTag /img/api/debug/debug-driver.jpg "Debug logs in browser" %} +{% imgTag /img/api/type/console-log-of-typing-with-entire-key-events-table-for-each-character.png "Console Log type" %} -## Log Cypress events +# 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 %}. +Cypress 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 +# 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: @@ -310,210 +126,10 @@ cy.now('task', 123) The `cy.now()` command is an internal command and may change in the future. {% endnote %} -## Log memory and CPU usage - -You can tell Cypress to log out a summary of the memory and CPU usage of itself and any subprocesses at a regular interval by enabling the `cypress:server:util:process_profiler` debug stream, like so: - -**On Mac or Linux:** - -```shell -DEBUG=cypress:server:util:process_profiler cypress run -``` - -**On Windows:** - -```shell -set DEBUG=cypress:server:util:process_profiler -cypress run -``` - -In the resulting output, processes are grouped by their name. - -{% imgTag /img/guides/troubleshooting-cypress-process-profiler-cli.jpg "Process printout of Cypress in CLI" %} - -By default, process information is collected and summarized is printed once every 10 seconds. You can override this interval by setting the `CYPRESS_PROCESS_PROFILER_INTERVAL` environment variable to the desired interval in milliseconds. - -You can also obtain more detailed per-process information by enabling the verbose `cypress-verbose:server:util:process_profiler` debug stream. - -## 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 run the Cypress app by itself are to: - -- 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 -``` - -If the smoke test does not show a specific error yet fails, try printing the Electron crash stack to maybe pinpoint the problem better: - -```shell -ELECTRON_ENABLE_STACK_DUMPING=1 npx cypress verify -... -Received signal 11 SEGV_MAPERR ffffffb27e8955bb -#0 0x55c6389f83d9 (/root/.cache/Cypress/3.8.2/Cypress/Cypress+0x35d13d8) -r8: 0000000000000000 r9: 00007ffcf0387c80 r10: 00007ffcf0387bd8 r11: 000000000000000e -r12: 00007ffcf0387d2c r13: 00007f3ea737b720 r14: ffffffb27e89558b r15: 00007f3ea8974200 -di: 0000000000000000 si: 0000000000000020 bp: 0000000000000000 bx: 0000004f2f375580 -dx: 0000000000000001 ax: 0000000000000030 cx: 0000000000000001 sp: 00007ffcf0387d00 -ip: 00007f3ea89582dd efl: 0000000000010246 cgf: 002b000000000033 erf: 0000000000000005 -trp: 000000000000000e msk: 0000000000000000 cr2: ffffffb27e8955bb -[end of stack trace] -Calling _exit(1). Core file will not be generated. -``` - -## Patch Cypress - -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/ %}. - -If you're encountering a bug in the current version of Cypress, you can implementing a temporary fix by patching Cypress in your own project. Here is an example of how to do this. - -1. Install {% url "patch-package" https://github.com/ds300/patch-package %}. -2. Add a patch step to your CI configuration after installing your npm packages. - - ```yaml - - run: npm ci - - run: npx patch-package - ``` - - Alternatively, you can apply the patch during a post-install phase. In your `package.json`, for example, you could add the following: - - ```json - { - "scripts": { - "postinstall": "patch-package" - } - } - ``` - -3. Edit the line causing the problem *in your local node_modules folder* within `node_modules/cypress`. -4. Run the `npx patch-package cypress` command. This command will create a new file `patches/cypress+3.4.1.patch`. - - ```shell - npx patch-package cypress - patch-package 6.1.2 - • Creating temporary folder - • Installing cypress@3.4.1 with npm - • Diffing your files with clean files - ✔ Created file patches/cypress+3.4.1.patch - ``` - -5. Commit the new `patches` folder to git. - -{% note info %} -If you find a patch for an error, please add a comment explaining your workaround to the relevant Cypress GitHub issue. It will help us release an official fix faster. -{% endnote %} - -## 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: +# Cypress fiddle -{% imgTag /img/guides/source-code.png "Source code of the Test Runner in a text editor" %} +While learning Cypress it may be a good idea to try small tests against some HTML. We have written a {% url @cypress/fiddle https://github.com/cypress-io/cypress-fiddle %} plugin for this. It can quickly mount any given HTML and run some Cypress test commands against it. -When finished, if necessary, remove the edited Test Runner version and reinstall the Cypress official version to get back to the official released code. +# Toubleshooting Cypress -```shell -rm -rf /Users/jane/Library/Caches/Cypress/3.3.1 -npm install cypress@3.3.1 -``` +There are times when you will encounter errors or unexpected behavior with Cypress itself. In this situation, we recommend checking our out {% url "Troubleshooting Guide" troubleshooting %}. diff --git a/source/guides/guides/launching-browsers.md b/source/guides/guides/launching-browsers.md index 4c9951be90..e6ef3d03aa 100644 --- a/source/guides/guides/launching-browsers.md +++ b/source/guides/guides/launching-browsers.md @@ -83,7 +83,7 @@ Or Microsoft Edge Canary (Chromium-based): cypress run --browser edge:canary ``` -{% url 'Having issues launching installed browsers? Read more about debugging browser launching' debugging#Launching-browsers %} +{% url 'Having issues launching installed browsers? Read more about troubleshooting browser launching' troubleshooting#Launching-browsers %} ## Firefox Browsers (beta) diff --git a/source/guides/references/configuration.md b/source/guides/references/configuration.md index 21046c40ea..f48fd6ce7e 100644 --- a/source/guides/references/configuration.md +++ b/source/guides/references/configuration.md @@ -102,6 +102,18 @@ Option | Default | Description ----- | ---- | ---- `nodeVersion` | `bundled` | If set to `system`, Cypress will try to find a Node executable on your path to use when executing your {% url plugins plugins-guide %}. Otherwise, Cypress will use the Node version bundled with Cypress. +The Node version printed in the Node.js Version panel is used in Cypress to: + +- Build files in the {% url "`integrationFolder`" configuration#Folders-Files %}. +- Build files in the {% url "`supportFolder`" configuration#Folders-Files %}. +- Execute code in the {% url "`pluginsFile`" configuration#Folders-Files %}. + +Cypress comes automatically bundled with a set Node version by default. + +You may want to use a different Node version if the code executing from the plugins file requires features present in a different Node version from the Node version bundled with Cypress. You can use the Node version detected on your system by setting the {% url "`nodeVersion`" configuration#Node-version %} configuration to `system`. + +{% imgTag /img/guides/test-runner-settings-nodejs-version.jpg "Node version in Settings in Test Runner" %} + # Overriding Options Cypress gives you the option to dynamically alter configuration values. This is helpful when running Cypress in multiple environments and on multiple developer machines. @@ -189,7 +201,14 @@ Cypress.config('pageLoadTimeout') // => 100000 # Resolved Configuration -When you open a Cypress project, clicking on the *Settings* tab will display the resolved configuration to you. This helps you to understand and see where different values came from. +When you open a Cypress project, clicking on the *Settings* tab will display the resolved configuration to you. This helps you to understand and see where different values came from. Each set value is highlighted to show where the value has been set via the following ways: + +- Default value +- The {% url "configuration file" configuration %} +- The {% url "Cypress environment file" environment-variables#Option-2-cypress-env-json %} +- System {% url "environment variables" environment-variables#Option-3-CYPRESS %} +- {% url "Command Line arguments" command-line %} +- {% url "Plugin file" configuration-api %} {% imgTag /img/guides/configuration/see-resolved-configuration.jpg "See resolved configuration" %} @@ -328,7 +347,7 @@ Run GC cleanup before every 3rd test during {% url "`cypress run`" command-line# ## Intelligent Code Completion -IntelliSense is available for Cypress while editing your configuration file. {% url "Learn how to set up Intelligent Code Completion." intelligent-code-completion %} +IntelliSense is available for Cypress while editing your configuration file. {% url "Learn how to set up Intelligent Code Completion." IDE-integration#Intelligent-Code-Completion %} {% history %} {% url "3.5.0" changelog %} | Added support for option `nodeVersion` diff --git a/source/guides/references/troubleshooting.md b/source/guides/references/troubleshooting.md new file mode 100644 index 0000000000..58b8bf0532 --- /dev/null +++ b/source/guides/references/troubleshooting.md @@ -0,0 +1,388 @@ +--- +title: Troubleshooting +--- + +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 %} + +You can see the full list of found browsers and their properties within the {% url "resolved configuration" configuration#Resolved-Configuration %} in the **Settings** tab of the Test Runner. + +Another way to log what is found by Cypress is to run Cypress with the {% urlHash "DEBUG environment variable" Print-DEBUG-logs %} set to `cypress:launcher`. This will print information about the found browsers and their properties to the terminal. + +## 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` +`chrome:canary` | `com.google.Chrome.canary` | `Contents/MacOS/Google Chrome Canary` + +For the current list, see {% url 'packages/launcher' https://github.com/cypress-io/cypress/blob/develop/packages/launcher/lib/darwin/index.ts %} files. + +## 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` +`chrome: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` +`chrome:canary` | `%APPDATA%/../Local/Google/Chrome SxS/Application/chrome.exe` + +For the current list, see {% url 'packages/launcher' https://github.com/cypress-io/cypress/blob/develop/packages/launcher/lib/windows/index.ts %} files. + +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 + +# 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 run +``` + +**On Windows:** + +```shell +set DEBUG=cypress:* +cypress run +``` + +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 memory and CPU usage + +You can tell Cypress to log out a summary of the memory and CPU usage of itself and any subprocesses at a regular interval by enabling the `cypress:server:util:process_profiler` debug stream, like so: + +**On Mac or Linux:** + +```shell +DEBUG=cypress:server:util:process_profiler cypress run +``` + +**On Windows:** + +```shell +set DEBUG=cypress:server:util:process_profiler +cypress run +``` + +In the resulting output, processes are grouped by their name. + +{% imgTag /img/guides/troubleshooting-cypress-process-profiler-cli.jpg "Process printout of Cypress in CLI" %} + +By default, process information is collected and summarized is printed once every 10 seconds. You can override this interval by setting the `CYPRESS_PROCESS_PROFILER_INTERVAL` environment variable to the desired interval in milliseconds. + +You can also obtain more detailed per-process information by enabling the verbose `cypress-verbose:server:util:process_profiler` debug stream. + +# 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 run the Cypress app by itself are to: + +- 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 +``` + +If the smoke test does not show a specific error yet fails, try printing the Electron crash stack to maybe pinpoint the problem better: + +```shell +ELECTRON_ENABLE_STACK_DUMPING=1 npx cypress verify +... +Received signal 11 SEGV_MAPERR ffffffb27e8955bb +#0 0x55c6389f83d9 (/root/.cache/Cypress/3.8.2/Cypress/Cypress+0x35d13d8) +r8: 0000000000000000 r9: 00007ffcf0387c80 r10: 00007ffcf0387bd8 r11: 000000000000000e +r12: 00007ffcf0387d2c r13: 00007f3ea737b720 r14: ffffffb27e89558b r15: 00007f3ea8974200 +di: 0000000000000000 si: 0000000000000020 bp: 0000000000000000 bx: 0000004f2f375580 +dx: 0000000000000001 ax: 0000000000000030 cx: 0000000000000001 sp: 00007ffcf0387d00 +ip: 00007f3ea89582dd efl: 0000000000010246 cgf: 002b000000000033 erf: 0000000000000005 +trp: 000000000000000e msk: 0000000000000000 cr2: ffffffb27e8955bb +[end of stack trace] +Calling _exit(1). Core file will not be generated. +``` + +## Patch Cypress + +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/ %}. + +If you're encountering a bug in the current version of Cypress, you can implementing a temporary fix by patching Cypress in your own project. Here is an example of how to do this. + +1. Install {% url "patch-package" https://github.com/ds300/patch-package %}. +2. Add a patch step to your CI configuration after installing your npm packages. + + ```yaml + - run: npm ci + - run: npx patch-package + ``` + + Alternatively, you can apply the patch during a post-install phase. In your `package.json`, for example, you could add the following: + + ```json + { + "scripts": { + "postinstall": "patch-package" + } + } + ``` + +3. Edit the line causing the problem *in your local node_modules folder* within `node_modules/cypress`. +4. Run the `npx patch-package cypress` command. This command will create a new file `patches/cypress+3.4.1.patch`. + + ```shell + npx patch-package cypress + patch-package 6.1.2 + • Creating temporary folder + • Installing cypress@3.4.1 with npm + • Diffing your files with clean files + ✔ Created file patches/cypress+3.4.1.patch + ``` + +5. Commit the new `patches` folder to git. + +{% note info %} +If you find a patch for an error, please add a comment explaining your workaround to the relevant Cypress GitHub issue. It will help us release an official fix faster. +{% endnote %} + +## 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 +``` diff --git a/source/guides/tooling/intelligent-code-completion.md b/source/guides/tooling/IDE-integration.md similarity index 87% rename from source/guides/tooling/intelligent-code-completion.md rename to source/guides/tooling/IDE-integration.md index 1bb29f29d7..048012c120 100644 --- a/source/guides/tooling/intelligent-code-completion.md +++ b/source/guides/tooling/IDE-integration.md @@ -1,32 +1,34 @@ --- -title: Intelligent Code Completion +title: IDE Integration --- -# Writing Tests +# Intelligent Code Completion -## Features +## Writing Tests + +### Features IntelliSense is available for Cypress. It offers intelligent code suggestions directly in your IDE while writing tests. A typical IntelliSense popup shows command definition, a code example and a link to the full documentation page. -### Autocomplete while typing Cypress commands +#### Autocomplete while typing Cypress commands {% video local /img/snippets/intellisense-cypress-assertion-matchers.mp4 %} -### Signature help when writing and hovering on Cypress commands +#### Signature help when writing and hovering on Cypress commands {% video local /img/snippets/intellisense-method-signature-examples.mp4 %} -### Autocomplete while typing assertion chains, including only showing DOM assertions if testing on a DOM element. +#### Autocomplete while typing assertion chains, including only showing DOM assertions if testing on a DOM element. {% video local /img/snippets/intellisense-assertion-chainers.mp4 %} -## Set up in your Dev Environment +### Set up in your Dev Environment This document assumes you have {% url "installed Cypress" installing-cypress %}. Cypress comes with TypeScript {% url "type declarations" https://github.com/cypress-io/cypress/tree/develop/cli/types %} included. Modern text editors can use these type declarations to show IntelliSense inside spec files. -### Triple slash directives +#### Triple slash directives The simplest way to see IntelliSense when typing a Cypress command or assertion is to add a {% url "triple-slash directive" "http://www.typescriptlang.org/docs/handbook/triple-slash-directives.html" %} to the head of your JavaScript or TypeScript testing file. This will turn the IntelliSense on a per file basis. Copy the comment line below and paste it into your spec file. @@ -50,7 +52,7 @@ See the {% url `cypress-example-todomvc` https://github.com/cypress-io/cypress-e If the triple slash directive does not work, please refer to your code editor in {% url "TypeScript's Editor Support doc" https://github.com/Microsoft/TypeScript/wiki/TypeScript-Editor-Support %} and follow the instructions for your IDE to get {% url "TypeScript support" typescript-support %} and intelligent code completion configured in your developer environment first. TypeScript support is built in for {% url "Visual Studio Code" https://code.visualstudio.com/ %}, {% url "Visual Studio" https://www.visualstudio.com/ %}, and {% url "WebStorm" https://www.jetbrains.com/webstorm/ %} - all other editors require extra setup. -### Reference type declarations via `jsconfig` +#### Reference type declarations via `jsconfig` Instead of adding triple slash directives to each JavaScript spec file, some IDEs (like VS Code) understand a common `jsconfig.json` file in the root of the project. In that file, you can include the Cypress module and your test folders. @@ -65,7 +67,7 @@ Instead of adding triple slash directives to each JavaScript spec file, some IDE The Intelligent Code Completion should now show help for `cy` commands inside regular JavaScript spec files. -### Reference type declarations via `tsconfig` +#### Reference type declarations via `tsconfig` Adding a {% url "`tsconfig.json`" http://www.typescriptlang.org/docs/handbook/tsconfig-json.html %} inside your {% url "`cypress` folder" writing-and-organizing-tests#Folder-Structure %} with the following configuration should get intelligent code completion working. @@ -84,21 +86,21 @@ Adding a {% url "`tsconfig.json`" http://www.typescriptlang.org/docs/handbook/ts } ``` -# Configuration +## Configuration -## Features: +### Features: When editing the {% url "configuration file (`cypress.json` by default)" configuration %}, you can use our {% url "json schema file" https://on.cypress.io/cypress.schema.json %} to get intelligent tooltips in your IDE for each configuration property. -### Property help when writing and hovering on configuration keys +#### Property help when writing and hovering on configuration keys {% video local /img/snippets/intellisense-cypress-config-tooltips.mp4 %} -### Properties list with intelligent defaults +#### Properties list with intelligent defaults {% video local /img/snippets/intellisense-config-defaults.mp4 %} -## Set up in your Dev Environment: +### Set up in your Dev Environment: Intelligent code completion using JSON schemas is supported by default in {% url "Visual Studio Code" https://code.visualstudio.com/ %} and {% url "Visual Studio" https://www.visualstudio.com/ %}. All other editors will require extra configuration or plugins for JSON schema support. @@ -125,4 +127,4 @@ Or you can directly add a `$schema` key to your Cypress configuration file, whic # See also -- {% url 'Adding custom properties to the global `window` with the right TypeScript type' https://github.com/bahmutov/test-todomvc-using-app-actions#intellisense %} +- {% url 'Adding custom properties to the global `window` with the right TypeScript type' https://github.com/bahmutov/test-todomvc-using-app-actions#intellisense %} \ No newline at end of file diff --git a/source/guides/tooling/typescript-support.md b/source/guides/tooling/typescript-support.md index 675efe6f17..80108d77a5 100644 --- a/source/guides/tooling/typescript-support.md +++ b/source/guides/tooling/typescript-support.md @@ -16,7 +16,7 @@ Just as you would when writing TypeScript files in your project, you will have t ## Set up your dev environment -Please refer to your code editor in {% url "TypeScript's Editor Support doc" https://github.com/Microsoft/TypeScript/wiki/TypeScript-Editor-Support %} and follow the instructions for your IDE to get TypeScript support and {% url "intelligent code completion" intelligent-code-completion %} configured in your developer environment before continuing. TypeScript support is built in for {% url "Visual Studio Code" https://code.visualstudio.com/ %}, {% url "Visual Studio" https://www.visualstudio.com/ %}, and {% url "WebStorm" https://www.jetbrains.com/webstorm/ %} - all other editors require extra setup. +Please refer to your code editor in {% url "TypeScript's Editor Support doc" https://github.com/Microsoft/TypeScript/wiki/TypeScript-Editor-Support %} and follow the instructions for your IDE to get TypeScript support and {% url "intelligent code completion" IDE-integration#Intelligent-Code-Completion %} configured in your developer environment before continuing. TypeScript support is built in for {% url "Visual Studio Code" https://code.visualstudio.com/ %}, {% url "Visual Studio" https://www.visualstudio.com/ %}, and {% url "WebStorm" https://www.jetbrains.com/webstorm/ %} - all other editors require extra setup. ## Configure tsconfig.json diff --git a/source/ja/faq/questions/using-cypress-faq.md b/source/ja/faq/questions/using-cypress-faq.md index cd96b046db..195462b750 100644 --- a/source/ja/faq/questions/using-cypress-faq.md +++ b/source/ja/faq/questions/using-cypress-faq.md @@ -141,7 +141,7 @@ We have seen many different iterations of this question. The answers can be vari **_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#One-Superdomain-per-Test %}, Cypress will log a verbose yet friendly error message. +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?_** diff --git a/source/ru/guides/overview/why-cypress.md b/source/ru/guides/overview/why-cypress.md index cfec3f1aff..1d28ffbdf4 100644 --- a/source/ru/guides/overview/why-cypress.md +++ b/source/ru/guides/overview/why-cypress.md @@ -43,7 +43,7 @@ Cypress может протестировать всё, что запускае # Экосистема Cypress -Cypress состоит из свободного, {% url "опенсорсного" https://github.com/cypress-io/cypress %}, {% url "устанавливаемого локально" installing-cypress %} приложения для запуска тестов (тест-раннера) **и** сервиса Dashboard для {% url 'записи ваших тестов' dashboard-service %}. +Cypress состоит из свободного, {% url "опенсорсного" https://github.com/cypress-io/cypress %}, {% url "устанавливаемого локально" installing-cypress %} приложения для запуска тестов (тест-раннера) **и** сервиса Dashboard для {% url 'записи ваших тестов' dashboard-introduction %}. - ***Сначала:*** Cypress позволяет просто настроить окружение и начать писать тесты каждый день во время локальной разработки вашего приложения. *TDD в лучшем виде!* - ***Далее:*** Создать набор тест-кейсов и {% url "интегрировать Cypress" continuous-integration %} с вашим CI-провайдером, а наш {% url 'сервис Dashboard' dashboard-introduction %} может записывать запуски ваших тестов. Вам никогда не придётся беспокоиться о том *Почему этот тест упал?* diff --git a/source/zh-cn/guides/dashboard/projects.md b/source/zh-cn/guides/dashboard/projects.md index efc09f917c..1fbc42dc55 100644 --- a/source/zh-cn/guides/dashboard/projects.md +++ b/source/zh-cn/guides/dashboard/projects.md @@ -73,7 +73,7 @@ Cypress uses your {% urlHash "`projectId`" 项目ID %} and {% urlHash "Record Ke export CYPRESS_PROJECT_ID={projectId} ``` -## 录制秘钥 {% fa fa-key %} +## 录制秘钥 Cypress使用你的`projectId`和*Record Key*，结合起来唯一标识你的项目。 diff --git a/source/zh-cn/guides/getting-started/writing-your-first-test.md b/source/zh-cn/guides/getting-started/writing-your-first-test.md index 2e20cb63e7..de0f80c5ff 100644 --- a/source/zh-cn/guides/getting-started/writing-your-first-test.md +++ b/source/zh-cn/guides/getting-started/writing-your-first-test.md @@ -219,7 +219,7 @@ describe('My First Test', function() { {% video local /img/snippets/first-test-click-30fps.mp4 %} {% note info %} -{% fa fa-magic %} 想在你的规格文件里面查看智能代码补全只需要添加一个单条注释哦. 阅读{% url '智能代码补全' intelligent-code-completion#Triple-slash-directives %}了解更多. +{% fa fa-magic %} 想在你的规格文件里面查看智能代码补全只需要添加一个单条注释哦. 阅读{% url '智能代码补全' IDE-integration#Triple-slash-directives %}了解更多. {% endnote %} ## {% fa fa-check-square-o %} 步骤4: 写断言 @@ -498,7 +498,7 @@ describe('My First Test', function() { # 下一步 - 开始{% url '测试你的app' testing-your-app %}. -- 为Cypress命令和断言设立{% url '智能代码补全' intelligent-code-completion %}. +- 为Cypress命令和断言设立{% url '智能代码补全' IDE-integration %}. - 搜索Cypress的文档说明书来更快的发现你需要的东西. {% imgTag /img/guides/search-box.png "Use the search box to find relevant documentation" %} diff --git a/source/zh-cn/guides/guides/command-line.md b/source/zh-cn/guides/guides/command-line.md index 694fea5c96..bbfc63f639 100644 --- a/source/zh-cn/guides/guides/command-line.md +++ b/source/zh-cn/guides/guides/command-line.md @@ -112,7 +112,7 @@ cypress run --browser /usr/bin/chromium 目前，仅支持Chrome家族的浏览器。 -{% url "有浏览器检测问题？看看调试指南吧！" debugging#Launching-browsers %} +{% url "有浏览器检测问题？看看调试指南吧！" troubleshooting#Launching-browsers %} ### `cypress run --ci-build-id ` @@ -323,7 +323,7 @@ cypress open --browser /usr/bin/chromium 当前，只有Chrome家族的浏览器是支持的。 -{% url "对使用浏览器有疑问？请阅读调试指南" debugging#Launching-browsers %}。 +{% url "对使用浏览器有疑问？请阅读调试指南" troubleshooting#Launching-browsers %}。 ### `cypress open --config ` diff --git a/source/zh-cn/guides/guides/launching-browsers.md b/source/zh-cn/guides/guides/launching-browsers.md index ecffb0832f..98387c5e79 100644 --- a/source/zh-cn/guides/guides/launching-browsers.md +++ b/source/zh-cn/guides/guides/launching-browsers.md @@ -65,7 +65,7 @@ cypress run --browser chromium cypress run --browser canary ``` -{% url '启动已安装的浏览器出现问题？请阅读关于调试浏览器启动的详细信息' debugging#Launching-browsers %} +{% url '启动已安装的浏览器出现问题？请阅读关于调试浏览器启动的详细信息' troubleshooting#Launching-browsers %} ## 通过路径启动 diff --git a/source/zh-cn/guides/references/configuration.md b/source/zh-cn/guides/references/configuration.md index ef0116635f..d13cafcda2 100644 --- a/source/zh-cn/guides/references/configuration.md +++ b/source/zh-cn/guides/references/configuration.md @@ -256,4 +256,4 @@ Cypress在网络级别修改这些脚本，因此搜索这些模式的响应流 ## 智能代码补全 -Cypress在编辑你的`cypress.json`文件时可以使用智能提示。{% url "了解如何设置智能代码补全。" intelligent-code-completion %} +Cypress在编辑你的`cypress.json`文件时可以使用智能提示。{% url "了解如何设置智能代码补全。" IDE-integration %} diff --git a/source/zh-cn/guides/tooling/typescript-support.md b/source/zh-cn/guides/tooling/typescript-support.md index 0a5e53a6ee..0d3fb2e515 100644 --- a/source/zh-cn/guides/tooling/typescript-support.md +++ b/source/zh-cn/guides/tooling/typescript-support.md @@ -16,7 +16,7 @@ Cypress使用{% url "TypeScript" https://www.typescriptlang.org/ %}作为{% url ## Set up your dev environment -Please refer to your code editor in {% url "TypeScript's Editor Support doc" https://github.com/Microsoft/TypeScript/wiki/TypeScript-Editor-Support %} and follow the instructions for your IDE to get TypeScript support and {% url "intelligent code completion" intelligent-code-completion %} configured in your developer environment before continuing. TypeScript support is built in for {% url "Visual Studio Code" https://code.visualstudio.com/ %}, {% url "Visual Studio" https://www.visualstudio.com/ %}, and {% url "WebStorm" https://www.jetbrains.com/webstorm/ %} - all other editors require extra setup. +Please refer to your code editor in {% url "TypeScript's Editor Support doc" https://github.com/Microsoft/TypeScript/wiki/TypeScript-Editor-Support %} and follow the instructions for your IDE to get TypeScript support and {% url "intelligent code completion" IDE-integration %} configured in your developer environment before continuing. TypeScript support is built in for {% url "Visual Studio Code" https://code.visualstudio.com/ %}, {% url "Visual Studio" https://www.visualstudio.com/ %}, and {% url "WebStorm" https://www.jetbrains.com/webstorm/ %} - all other editors require extra setup. ## Configure tsconfig.json diff --git a/themes/cypress/languages/en.yml b/themes/cypress/languages/en.yml index ae05bd3340..26682a51e2 100644 --- a/themes/cypress/languages/en.yml +++ b/themes/cypress/languages/en.yml @@ -62,11 +62,12 @@ sidebar: assertions: Assertions best-practices: Best Practices trade-offs: Trade-offs + troubleshooting: Troubleshooting changelog: Changelog migration-guide: Migration Guide roadmap: Roadmap tooling: Tooling - intelligent-code-completion: Intelligent Code Completion + IDE-integration: IDE Integration plugins-guide: Plugins reporters: Reporters typescript-support: TypeScript diff --git a/themes/cypress/languages/ja.yml b/themes/cypress/languages/ja.yml index a1b64b25a0..4a0a603f88 100644 --- a/themes/cypress/languages/ja.yml +++ b/themes/cypress/languages/ja.yml @@ -62,11 +62,12 @@ sidebar: assertions: アサーション best-practices: ベストプラクティス trade-offs: トレードオフ + troubleshooting: Troubleshooting changelog: 変更履歴 migration-guide: Migration Guide roadmap: ロードマップ tooling: ツール - intelligent-code-completion: コード自動補完 + IDE-integration: IDE Integration plugins-guide: プラグイン reporters: レポーター typescript-support: TypeScript diff --git a/themes/cypress/languages/pt-br.yml b/themes/cypress/languages/pt-br.yml index c56d034473..f529d11af2 100644 --- a/themes/cypress/languages/pt-br.yml +++ b/themes/cypress/languages/pt-br.yml @@ -62,11 +62,12 @@ sidebar: assertions: Asserções best-practices: Boas Práticas trade-offs: Trade-offs + troubleshooting: Troubleshooting changelog: Changelog migration-guide: Migration Guide roadmap: Roteiro tooling: Ferramentas - intelligent-code-completion: Conclusão Inteligente de Código + IDE-integration: IDE Integration plugins-guide: Plugins reporters: Reporters typescript-support: TypeScript diff --git a/themes/cypress/languages/ru.yml b/themes/cypress/languages/ru.yml index daf49be6b9..09b5862f5a 100644 --- a/themes/cypress/languages/ru.yml +++ b/themes/cypress/languages/ru.yml @@ -62,11 +62,12 @@ sidebar: assertions: Ассерты best-practices: Лучшие практики trade-offs: Компромиссы + troubleshooting: Troubleshooting changelog: Изменения в продукте migration-guide: Migration Guide roadmap: Карта проекта tooling: Утилиты - intelligent-code-completion: Интеллектуальное завершение кода + IDE-integration: IDE Integration plugins-guide: Плагины reporters: Репортеры typescript-support: TypeScript diff --git a/themes/cypress/languages/zh-cn.yml b/themes/cypress/languages/zh-cn.yml index 8db469fe9b..fc548a8f1f 100644 --- a/themes/cypress/languages/zh-cn.yml +++ b/themes/cypress/languages/zh-cn.yml @@ -64,11 +64,12 @@ sidebar: assertions: 断言 best-practices: 最佳实践 trade-offs: 取舍 + troubleshooting: Troubleshooting changelog: 更新日志 migration-guide: Migration Guide roadmap: 路线图 tooling: 工具 - intelligent-code-completion: 代码智能补全 + IDE-integration: IDE Integration plugins-guide: 插件 reporters: 报告生成器 typescript-support: TypeScript diff --git a/themes/cypress/source/img/guides/test-runner-settings-nodejs-version.jpg b/themes/cypress/source/img/guides/test-runner-settings-nodejs-version.jpg new file mode 100644 index 0000000000..9d170bfc24 Binary files /dev/null and b/themes/cypress/source/img/guides/test-runner-settings-nodejs-version.jpg differ