From 1bbe725830dbe8cda08f00f24d97b559893116d5 Mon Sep 17 00:00:00 2001
From: Preston Goforth <p@osano.com>
Date: Fri, 14 Apr 2023 17:23:16 -0400
Subject: [PATCH] feat: Add documentation for `stripCspDirectives` and CSP
 information

---
 .../guides/guides/content-security-policy.mdx | 36 ++++++++++++++++
 docs/guides/references/configuration.mdx      | 43 +++++++++++++++++++
 2 files changed, 79 insertions(+)
 create mode 100644 docs/guides/guides/content-security-policy.mdx

diff --git a/docs/guides/guides/content-security-policy.mdx b/docs/guides/guides/content-security-policy.mdx
new file mode 100644
index 00000000000..a4e53a796d6
--- /dev/null
+++ b/docs/guides/guides/content-security-policy.mdx
@@ -0,0 +1,36 @@
+---
+title: Content Security Policy
+e2eSpecific: true
+---
+
+Content Security Policy (CSP) is a browser security feature that allows you to
+restrict the resources that can be loaded into your application. This can be
+problematic for Cypress, because it needs to inject JavaScript into your
+application in order to run tests and interact with the DOM. This page describes
+how Cypress handles CSP and how to configure it to work with your application.
+
+There are two ways to implement CSP:
+
+- [Meta tag](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/meta#http-equiv)
+- [HTTP header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy)
+
+The `<meta>` tag implementation is fully supported by Cypress without any
+configuration required. This is because Cypress loads the necessary `<script>`
+tags into your application before any `<meta>` tag is parsed. This prevents any
+CSP directives from being applied to the script loaded by Cypress.
+
+The second implementation requires you to configure Cypress to allow the headers
+to be sent to your application. By default, Cypress will remove any CSP headers
+from the response before it is sent to the browser. This is done to prevent
+Cypress from being blocked by the browser's CSP implementation.
+
+For most application tests, this should not cause any issues. However, if you
+are testing your application's CSP implementation, you will need to configure
+Cypress to allow the headers to be sent to the browser. You can do this by
+setting the
+[`stripCspDirectives`](/guides/references/configuration#stripCspDirectives)
+configuration option.
+
+For more information on CSP, see the
+[Content Security Policy](https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP)
+documentation on MDN.
diff --git a/docs/guides/references/configuration.mdx b/docs/guides/references/configuration.mdx
index c2ce5aa4a3f..e0f3feda880 100644
--- a/docs/guides/references/configuration.mdx
+++ b/docs/guides/references/configuration.mdx
@@ -76,6 +76,7 @@ default values.
 | `reporter`             | `spec`                            | The [reporter](/guides/tooling/reporters) used during `cypress run`.                                                                                                                         |
 | `reporterOptions`      | `null`                            | The [reporter options](/guides/tooling/reporters#Reporter-Options) used. Supported options depend on the reporter.                                                                           |
 | `retries`              | `{ "runMode": 0, "openMode": 0 }` | The number of times to retry a failing test. Can be configured to apply to `cypress run` or `cypress open` separately. See [Test Retries](/guides/guides/test-retries) for more information. |
+| `stripCspDirectives`   | `true`                            | Indicates the Content-Security-Policy directives to be stripped during a test run. See [Content-Security-Policy](/guides/guides/content-security-policy) for more information.               |
 | `watchForFileChanges`  | `true`                            | Whether Cypress will watch and restart tests on test file changes.                                                                                                                           |
 
 ### Timeouts
@@ -363,6 +364,7 @@ readonly and cannot be changed at run time.
 - `screenshotOnRunFailure`
 - `scrollBehavior`
 - `slowTestThreshold`
+- `stripCspDirectives`
 - `testIsolation` - this option can only be overridden at the suite-specific
   override level
 - `viewportHeight`
@@ -682,6 +684,47 @@ This function was added in Cypress version `10.0.0` to replace the deprecated
 
 See the [plugins guide](/guides/tooling/plugins-guide) for more information.
 
+### stripCspDirectives
+
+Cypress will (by default) strip all CSP headers from the response before it is
+sent to the browser. This option allows for more granular control over which CSP
+directives are stripped from the CSP response headers, allowing you to test your
+application with CSP enabled.
+
+#### Strip All CSP Headers
+
+The default value of `stripCspDirectives` is `"all"`. This will remove all CSP
+headers from the response before it is sent to the browser. This option should
+be used if you do not depend on CSP for any tests in your application.
+
+#### Strip Minimum CSP Directives
+
+If you need to test your application with CSP enabled, you can set the
+`stripCspDirectives` option to `"minimum"`. This will allow all CSP headers to
+be sent to the browser _*except*_ those that would prevent Cypress from
+functioning Normally. The following CSP directives are automatically stripped
+from the CSP headers when `stripCspDirectives` is set to `"minimum"`:
+
+| Stripped Directive | Reason                                                                          |
+| ------------------ | ------------------------------------------------------------------------------- |
+| `frame-ancestors`  | This directive prevents Cypress from loading a test application into an iframe. |
+
+#### Strip Specific CSP Directives
+
+If you need to test your application with CSP enabled, but need to strip
+specific CSP directives, you can set the `stripCspDirectives` option to an array
+of directive names. This will allow all CSP directives to be sent to the browser
+_except_ those that are defined in the `stripCspDirectives` array.
+
+:::caution
+
+Defining `stripCspDirectives` _*without*_ including the directives listed in the
+[minimum directives table](#Strip-Minimum-CSP-Directives) will potentially cause
+Cypress to be unable to run tests against your application. This may be desired
+if you are testing against specific CSP directives.
+
+:::
+
 ## Common problems
 
 #### <Icon name="angle-right" /> `baseUrl` is not set