feat: Add documentation for stripCspDirectives and CSP information

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 to `false`.
+
+For more information on CSP, see the
+[Content Security Policy](https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP)
+documentation on MDN.

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,51 @@ 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 `true`. 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.
+
+#### Do Not Strip Any CSP Directives
+
+If you need to test your application with CSP enabled, you can set the
+`stripCspDirectives` option to `false`. This will allow all CSP headers to be
+sent to the browser _*except*_ those that would actively prevent Cypress from
+running your application in an iframe. The following CSP directives are
+automatically stripped from the CSP headers when `stripCspDirectives` is set to
+`false`:
+
+| 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
+
+<strong>frame-ancestors</strong>
+
+Defining `stripCspDirectives` _*without*_ including `frame-ancestors` will
+prevent Cypress from loading your application into an iframe. Since this may be
+desired if you are testing a web application that is not intended to be loaded
+into an iframe, this option is not automatically included when defining
+individual directives in the `stripCspDirectives` array.
+
+:::
+
 ## Common problems
 
 #### <Icon name="angle-right" /> `baseUrl` is not set