From 9c0d2ce099c5f7ff4d5d536161360ff0ae97c6aa Mon Sep 17 00:00:00 2001 From: Bill Glesias Date: Wed, 23 Nov 2022 12:00:07 -0500 Subject: [PATCH 01/18] re-add websecurity, links to websecurity, and trade-offs guides --- content/_data/sidebar.json | 4 + content/faq/questions/using-cypress-faq.md | 2 + .../guides/guides/cross-browser-testing.md | 2 +- content/guides/guides/web-security.md | 417 ++++++++++++++++++ content/guides/references/error-messages.md | 5 + .../guides/references/legacy-configuration.md | 2 +- content/guides/references/trade-offs.md | 88 ++++ 7 files changed, 518 insertions(+), 2 deletions(-) create mode 100644 content/guides/guides/web-security.md diff --git a/content/_data/sidebar.json b/content/_data/sidebar.json index d32bf3a13d..478280546d 100644 --- a/content/_data/sidebar.json +++ b/content/_data/sidebar.json @@ -320,6 +320,10 @@ { "title": "Cross Browser Testing", "slug": "cross-browser-testing" + }, + { + "title": "Web Security", + "slug": "web-security" } ] }, diff --git a/content/faq/questions/using-cypress-faq.md b/content/faq/questions/using-cypress-faq.md index aa59f6148f..2ae7ec531f 100644 --- a/content/faq/questions/using-cypress-faq.md +++ b/content/faq/questions/using-cypress-faq.md @@ -919,6 +919,8 @@ application under test runs in any way, so you can safely ignore this warning. The network traffic between Cypress and the backend server still happens via HTTPS. +See also the [Web Security](/guides/guides/web-security) guide. + ## Is there an option to run Cypress in CI with Developer Tools open? We want to track network and console issues. No. There is not currently a way to run Cypress in `cypress run` with Developer diff --git a/content/guides/guides/cross-browser-testing.md b/content/guides/guides/cross-browser-testing.md index 47f666822c..6cbbe3fa22 100644 --- a/content/guides/guides/cross-browser-testing.md +++ b/content/guides/guides/cross-browser-testing.md @@ -14,7 +14,7 @@ browser engine), and Firefox. Web Security Tests that require the -[`chromeWebSecurity` configuration option to be disabled](/guides/references/configuration#Browser) +[`chromeWebSecurity` configuration option to be disabled](/guides/guides/web-security#Disabling-Web-Security) may experience issues in non-Chromium based browsers. diff --git a/content/guides/guides/web-security.md b/content/guides/guides/web-security.md new file mode 100644 index 0000000000..49df21fbc8 --- /dev/null +++ b/content/guides/guides/web-security.md @@ -0,0 +1,417 @@ +--- +title: Web Security +e2eSpecific: true +--- + +Browsers adhere to a strict +[same-origin policy](https://developer.mozilla.org/en-US/docs/Web/Security/Same-origin_policy). +This means that browsers restrict access between `` when their origin +policies do not match. + +Because Cypress works from within the browser, Cypress must be able to directly +communicate with your remote application at all times. Unfortunately, browsers +naturally try to prevent Cypress from doing this. + +To get around these restrictions, Cypress implements some strategies involving +JavaScript code, the browser's internal APIs, and network proxying to _play by +the rules_ of same-origin policy. It is our goal to fully automate the +application under test without you needing to modify your application's code - +and we are _mostly_ able to do this. + +#### Examples of what Cypress does under the hood: + +- Injects + [`document.domain`](https://developer.mozilla.org/en-US/docs/Web/API/Document/domain) + into `text/html` pages. +- Proxies all HTTP / HTTPS traffic. +- Changes the hosted URL to match that of the application under test. +- Uses the browser's internal APIs for network level traffic. + +When Cypress first loads, the internal Cypress web application is hosted on a +random port: something like `http://localhost:65874/__/`. + +After the first [`cy.visit()`](/api/commands/visit) command is issued in a test, +Cypress changes its URL to match the origin of your remote application, thereby +solving the first major hurdle of same-origin policy. Your application's code +executes the same as it does outside of Cypress, and everything works as +expected. + + + +How is HTTPS supported? + +Cypress does some pretty interesting things under the hood to make testing HTTPS +sites work. Cypress enables you to control and stub at the network level. +Therefore, Cypress must assign and manage browser certificates to be able to +modify the traffic in real time. + +You'll notice Chrome display a warning that the 'SSL certificate does not +match'. This is normal and correct. Under the hood we act as our own CA +authority and issue certificates dynamically in order to intercept requests +otherwise impossible to access. We only do this for the superdomain currently +under test, and bypass other traffic. That's why if you open a tab in Cypress to +another host, the certificates match as expected. + +Note, that Cypress allows you to optionally specify CA / client certificate +information for use with HTTPS sites. See +[Configuring client certificates](/guides/references/client-certificates). If +the remote server requests a client certificate for a configured URL, Cypress +will supply it. + + + +## Limitations + +It's important to note that although we do our **very best** to ensure your +application works normally inside of Cypress, there _are_ some limitations you +need to be aware of. + +### Same superdomain per test + +::include{file=partials/single-domain-workaround.md} + +Because Cypress changes its own host URL to match that of your applications, it +requires that the URLs navigated to have the same superdomain for the entirety +of a single test. + +If you attempt to visit two different superdomains, Cypress will error. Visiting +subdomains works fine. You can visit different superdomains in _different_ +tests, but not in the _same_ test. + +```javascript +it('navigates', () => { + cy.visit('https://www.cypress.io') + cy.visit('https://docs.cypress.io') // yup all good +}) +``` + +```javascript +it('navigates', () => { + cy.visit('https://apple.com') + cy.visit('https://google.com') // this will error +}) +``` + +```javascript +it('navigates', () => { + cy.visit('https://apple.com') +}) + +// split visiting different origin in another test +it('navigates to new origin', () => { + cy.visit('https://google.com') // yup all good +}) +``` + +Although Cypress tries to enforce this limitation, it is possible for your +application to bypass Cypress's ability to detect this. + +#### Examples of test cases that will error due to superdomain limitations + +1. [`.click()`](/api/commands/click) an `` with an `href` to a different + superdomain. +2. [`.submit()`](/api/commands/submit) a `
` that causes your web server to + redirect to you a different superdomain. +3. Issue a JavaScript redirect in your application, such as + `window.location.href = '...'`, to a different superdomain. + +In each of these situations, Cypress will lose the ability to automate your +application and will immediately error. + +Read on to learn about +[working around these common problems](/guides/guides/web-security#Common-Workarounds) +or even +[disabling web security](/guides/guides/web-security#Disabling-Web-Security) +altogether. + +### Cross-origin iframes + +If your site embeds an `