Cypress - v0.20.0

Released 09/10/2017

Summary:

• 0.20.0 is our biggest technical release ever. It accounts for more than 2,000 commits. It's full of breaking changes we wanted to land prior to having our public 1.0.0 release.
• You can now install Cypress as a real npm module, and even require it in your node files.
• We rewrote the entire driver (we've all been there) and converted all 2,500+ tests to be run within Cypress itself.

CLI Changes:

• You now use npm to manage Cypress versions like every other dev dependency.
• Running npm install --save-dev cypress will automatically download the CLI + binary.
• There is no longer a separate cypress install step, but this command still exists if you want to reinstall the binary for whatever reason.
• No need to use cypress-cli anymore to manage Cypress versions. You will need to uninstall the cypress-cli by running npm uninstall -g cypress-cli.
• The cypress module can be required in your own node projects to programmatically control Cypress the same way you would from the command line.
• We've updated the installation experience to account for running locally and in CI so it doesn't generate a ton of logs in stdout.
• The CYPRESS_VERSION environment variable is gone because now the version of the binary is controlled by the npm module version. If for some reason you want to download the binary of a different version you can use the new CYPRESS_BINARY_VERSION environment variable - but you'll get a warning message when the versions don't match.
• If you install cypress globally using npm install -g cypress we will warn you that you should check this in as a devDependency but Cypress will continue to work in "global mode".
• Cypress now verifies it can run on your system prior to actually running. It'll do this for each new version the first time you try to use it. Errors it receives from attempting to run will bubble up nicely, so you'll get output for things like missing linux dependencies instead of absolutely nothing like before.
• We have better error handling and messaging around Xvfb failures.
• There is a new --browser option that lets you change the browser that runs from the command line. This works the same way as changing the browser in the GUI, with the exception that any browser other than the default electron browser will not record a video. This is solvable but requires more work.
• Whenever you encounter errors in the CLI we'll output helpful debugging information at the bottom of each error.
• You can use the new environment variable DEBUG=cypress:cli to see debugging output from the CLI.

Breaking Changes:

• We've removed the undocumented cy.chain() command. You should be able to safely remove this from your code. Fixes #456.
• Updated Cypress._ to use lodash instead of Underscore. Fixes #548.
• If any of an element's parent's overflow is 'hidden', we now calculate if the element is outside of the boundaries of that parent element and validate visibility assertions accordingly. This may cause some tests that were previously passing to now accurately fail. Fixes #410.
• .select() should now look for the trimmed value inside of an <option></option>. This may change the content argument required to select the option you intended in your .select() command. Fixes #175.
• When passing the option { force: true } to .click() and .type(), we no longer attempt to scroll the element into view. We've also disabled the check that the element is in view before clicking or typing. Fixes #553 and #537.
• Cypress.Dom has been renamed to Cypress.dom.
• Cypress.Log.command has been renamed to Cypress.log.
• chai-jQuery assertions no longer change the subject when using prop, attr, and css with the 3rd argument (which acts as equality check). Fixes #605.
• We now throw when a value other than cy is returned from a test or command function. Fixes #463.
• Returning a promise in a custom command while also invoking cy commands now throws. Fixes #435.
• cy.then() will now only pass its subject through when its callback function returns undefined. Previous it would pass the subject on null values as well.
• cy.contains() can no longer be chained on subjects which aren't window, document or element. This brings it into parity with the new custom command rules and makes it much less "magical". It enforces you to use it in a much clearer way when querying the entire document.
• Removed Cypress.addParentCommand(), Cypress.addChildCommand(), and Cypress.addDualCommand() in favor of the new custom command interface.

Features:

• chai-jQuery assertions have improved error messaging, and have had their internal double assertions removed, and can now be made on raw DOM objects. Fixes #605.
• chai-jQuery assertions now throw a nice error message when you're asserting on a non DOM object. Fixes #604.
• New .trigger() command. Useful for triggering arbitrary events. Fixes #406.
• New cy.scrollTo() command. Useful for having a container scroll to a specific position. Fixes #497 & #313.
• New .scrollIntoView() command. Useful for scrolling an element into view. Fixes #498 & #313 & #519.
• Input ranges are now more easily testable using the new .trigger() command. See our new recipe for details on how. Fixes #287.
• Testing drag and drop is now possible using the new .trigger() command. See our new recipe for details on how. Fixes #386.
• Updated .click() command to accept more position arguments. Fixes #499.
• Added support to .type() for inputs of type date, time, month, and week. Fixes #27.
• You can now pass a browser option to cypress run as --browser <browser name>. This enables you to run the same set of browsers when running from the CLI as when you're running from the GUI. Fixes #462 and #531.
• cypress open no longer opens a detached process by default. Instead cypress open now accepts a new flag --detached, which replicates this behavior. Fixes #531.
• We have all new docker examples you can check out.
• The cypress npm package now checks the currently installed version on install and run and does not re-install Cypress if it is already installed. Fixes #396.
• We've added a new Cypress.Commands interface to handle adding your own custom commands. Fixes #436.
• You can now overwrite existing commands with Cypress.Commands.overwrite.
• We removed an artificial delay that was being set in between commands. This means test commands now run faster.
• You can now disable Cypress global exception handlers for your application. Fixes #254
• Uncaught errors appearing in your spec files or support files are now properly caught, have the right exit code, and display correctly. Fixes #345
• Cypress will now scroll past multiple elements that cover up an element to be interacted with. It also now factors in elements with position: sticky. Fixes #571 and #565.
• Cypress now scrolls all parent containers (not just window) when attempting to check an element's actionability. Fixes #569.
• Using Chai.js's assert interface now works correctly in your specs.
• Screenshots are now taken during each runnable that fails. Errors in tests will happen there. Errors in hooks will also happen there. Previously a screenshot would only happen after everything (including hooks) ran. Fixes #394
• cy.screenshot() now synchronizes its state with the reporter. This means you should see error messages (on the left side) on automatic screenshot errors.
• Using mocha's async done callback now works properly.
• You can now programmatically intercept and potentially turn off uncaught application errors from failing your tests.
• You can now programmatically control whether you accept or cancel window.confirm() calls from your application.

Dependencies:

• Updated Cypress.Promise (which is Bluebird) from version 2.9.25 to 3.5.0
• Updated chai from version 1.9.2 to 3.5.0
• Updated sinon from version 1.x to 3.2.0
• Updated "jQuery" $ from version 2.1.4 to 2.2.4.
• Removed chai-jQuery and rewrote it from scratch.

Deprecations:

• The cypress-cli npm package has been deprecated. Fixes #316.
• The interface for writing custom commands has been deprecated. Please read our docs on the new custom commands interface. Fixes #436 and #465.
• There are no more global, in-app updates. Versioning should be primarily controlled via npm like every other package / dependency in your project. For users not using npm you can manually download new versions of Cypress when they're released.

Bugfixes:

• Fixed busted internal timers that caused random timeouts, proxy errors, incorrect delays, and long pauses when loading the GUI. Fixes #572.
• cy.route() now matches requests opened with lowercase methods. Fixes #607.
• Fixed regression where multiple uses of cy.server() in a before hook was throwing an error. Fixes #80 and #510 and #595.
• When editing cypress.json file, the dead browser page no longer appears. Fixes #492.
• .type() should now work on inputs regardless of capitalization of type attribute. Fixes #550.
• Fixed issues where .type() was not appending text properly. Fixes #503 and #568.
• Fixed issue where .type() with type="email" inputs were throwing an error. Fixes #504.
• Fixed issue where using .type() on an input with a type defined in uppercase (input type="TEXT") would throw an error and not type. Fixes #550.
• Fixed issue with .clear() and type="number" inputs. Fixes #490.
• Fixed issue where cy.exec() was failing when running Cypress in docker. Fixes #517.
• Cypress CLI no longer requires git to install. Fixes #124
• Improved the reporter's responsive design so controls still show at narrower widths. Fixes #544.
• Commands text will no long cut off into ellipses when the Command Log is set to a wider width. Fixes #528.
• Fixed issue where setting fixturesFolder to false would throw an error. Fixes #450.
• Fixed issue where Cypress hanged due to Xvfb permissions. More intuitive output is given during install failures. Fixes #330.
• The checks used to determine an element's actionability are now run synchronously. This solves some circumstances where the element could have moved or otherwise change between the checks. Fixes #570.
• Fixed issue where clipped elements with overflow-y: hidden were falsely passing as "visible". Fixes #563.
• When using .select() on a select with multiple options with the same value, we now properly set selectedIndex and selectedOptions on the select. Fixes #554.
• Fixed issue where changing any spec file (renaming, adding, deleting) would remove the highlighted styling of the currently active spec file in the Test Runner. Fixes #547.
• We now get the absolute paths of styles to use when displaying snapshots. This will fix situations where some stylesheets were improperly referenced during the snapshot, so did not display styles correctly. Fixes #525.
• Fixed issue where commands would retry and potentially exceed their timeout values during page transitions. Fixes #594
• Fixed issue where server routes were lost after page load if not initiated by a cy.visit() command. Fixes #177
• Using mocha's done callback now works correctly. We've improved mocha's handling of uncaught exceptions and properly associate them to test failures.
• cy.viewport() is now synchronized with the UI so that it does not resolve until the DOM has re-rendered using the dimensions.
• "outer assertions" now are correctly retried by previous commands. Fixes #543.
• The example_spec from the kitchen-sink will never accidentally be seeded when running cypress run on a brand new project.

Misc:

• We now display a warning in the console when returning a promise from a test and also invoking a Promise or cy commands. Fixes #464.
• Reduced the number of internal Cypress network requests in the "Network Panel" of Dev Tools. Fixes #606.
• We've moved our entire codebase into one into a private "Monorepo". This is in anticipation for going open source (making the GitHub repo public) and should make it easier for everyone to contribute to our code. Fixes #256.
• When element's are not visible due to being covered by another element, the error message now says what element is covering what element. #611
• Improved the calculations to calculate an elements visibility. Additionally updated error messages to be clearer whenever an element isn't considered visible. Fixes #613
• The "Can't start server" error displayed in the Desktop-GUI no longer prevents you from interacting in the Desktop App. It now displays as a warning. Fixes #407.
• cy.focused() now automatically retries until the element exists in the DOM. This makes it behave the same as cy.get() Fixes #564 and #409.
• We now support per-project state.json. Fixes #512.
• We can now handle multiple projects per server. Fixes #512.
• The Test Runner can now have projects added by being 'dragged' in. Fixes .
• The Test Runner update window now has messaging about package.json versioning. Fixes #513.
• The Test Runner now accounts for cypress being installed per project as npm module. Fixes #500 and #514.
• cypress install -d option. Fixes #389.
• Exposing Cypress Binary should no longer be necessary when cypress is locally installed. Fixes #379.
• Added an 'App Data' option in the Desktop App that displays app data. Fixes #475.
• When cy.spy() or cy.stub() are never called, the error now displays a clearer, grammatically correct error. Fixes #520.
• Detection of installed browsers has been improved. Fixes #511.
• When commands are clicked on and logged into the console from the Command Log, they now display their 'yield' instead of 'return', since they really yield instead of return. #612
• The build process of the driver has been modernized. Fixes #429.
• XHR's from your application are no longer forcefully aborted between tests.
• Better error handling when running commands outside of a test.
• URL changes from navigation events or hashchanges now display more accurately.
• cy.go() now snapshots before and after the navigation event.
• Page load events no longer forcibly null out the current subject. This was very unexpected and difficult to debug. Now stale elements or other objects from previous pages are yielded to you.
• Using an array of the same alias in a cy.wait() now yields you those XHR's in the order they were requested. Previously it was based on when the responses were returned.
• Returning null from a .then() will now change the subject to that. Previously returning null would not cause subject changes.
• We now no longer remove spies, stubs, or routes at the end of the very last test. This enables you to continue to manually use your app and have Cypress continue to instrument it.
• Updated a few things to more aggressively cause GC.
• Onboarding dialogs will never show up again once they are dismissed. Fixes #522.
• window.alert() and window.confirm() now generate a page event in the Command Log (including the message).
• cy.spy() and cy.stub() now have a .log(bool) method to disable their calls from generating a Command Log. Useful when your spies or stubs are called an excessive number of times.
• Improved command subject validation error messages.
• Improved the element detachment error messages (when you try to interact with an element that's become stale / detached from the document).
• We finally have partial iframe support. You can at least now cy.wrap() iframe elements and interact with them using Cypress commands. More work needs to be done to "switch into" and back "out of" iframes. But we're getting there.
• Scaffolding new projects no longer generates a default.js file.
• Scaffolded index.js and commands.js have had their content updated to point to the custom commands API.
• You can now call .focus() and .blur() on cy.window().
• The CYPRESS_DEBUG env option has been removed in favor of the debug module and DEBUG=cypress:* usage.
• Attempting to run cypress run on a project without a cypress.json now errors instead of scaffolding and running the kitchen sink.

Documentation Changes:

Note: we are still updating all of the docs to reflect all the 0.20.0 changes.

• New "Catalog of Events"
• New "Cypress.Commands"
• New "Cypress.log"
• New ".trigger()"
• New "cy.scrollTo()"
• New ".scrollIntoView()"
• Updated "Installing Cypress"
• Updated "Writing Your First Test"
• Updated "Testing Your App"
• Updated "Command Line"
• Updated "Debugging"
• Updated "Assertions"
• Updated "Interacting with Elements"