Skip to content

Commit

Permalink
feat: Add documentation for experimentalCspAllowList
Browse files Browse the repository at this point in the history 
- Remove more general `stripCspDirectives` documentation
  • Loading branch information
@pgoforth
pgoforth committed May 23, 2023
1 parent 405b50c commit 7a50b35
Show file tree
Hide file tree
Showing 3 changed files with 52 additions and 44 deletions.
2 changes: 1 addition & 1 deletion docs/guides/guides/content-security-policy.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,7 @@ 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)
[`experimentalCspAllowList`](/guides/references/experiments#Experimental-CSP-Allow-List)
configuration option.

For more information on CSP, see the
Expand Down
43 changes: 0 additions & 43 deletions docs/guides/references/configuration.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -76,7 +76,6 @@ 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` | `all` | 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
Expand Down Expand Up @@ -364,7 +363,6 @@ 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`
Expand Down Expand Up @@ -684,47 +682,6 @@ 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
Expand Down
51 changes: 51 additions & 0 deletions docs/guides/references/experiments.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -25,13 +25,64 @@ configuration to Cypress.

| Option | Default | Description |
| --------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `experimentalCspAllowList` | `false` | Indicates the Content-Security-Policy directives to be permitted during a test run. See [Content-Security-Policy](/guides/guides/content-security-policy) for more information. |
| `experimentalFetchPolyfill` | `false` | Automatically replaces `window.fetch` with a polyfill that Cypress can spy on and stub. Note: `experimentalFetchPolyfill` has been deprecated in Cypress 6.0.0 and will be removed in a future release. Consider using [cy.intercept()](/api/commands/intercept) to intercept `fetch` requests instead. |
| `experimentalInteractiveRunEvents` | `false` | Allows listening to the [`before:run`](/api/plugins/before-run-api), [`after:run`](/api/plugins/after-run-api), [`before:spec`](/api/plugins/before-spec-api), and [`after:spec`](/api/plugins/after-spec-api) events in the [setupNodeEvents](/guides/tooling/plugins-guide#Using-a-plugin) function during interactive mode. |
| `experimentalMemoryManagement` | `false` | Enables support for improved memory management within Chromium-based browsers. |
| `experimentalModifyObstructiveThirdPartyCode` | `false` | Whether Cypress will search for and replace obstructive code in third party `.js` or `.html` files. NOTE: Setting this flag removes [Subresource Integrity (SRI)](https://developer.mozilla.org/en-US/docs/Web/Security/Subresource_Integrity). |
| `experimentalSourceRewriting` | `false` | Enables AST-based JS/HTML rewriting. This may fix issues caused by the existing regex-based JS/HTML replacement algorithm. See [#5273](https://github.com/cypress-io/cypress/issues/5273) for details. |
| `experimentalWebKitSupport` | `false` | Enable experimental support for running tests in WebKit. When set, installs of `playwright-webkit` will be detected and available in Cypress. See [Launching Browsers](/guides/guides/launching-browsers#WebKit-Experimental) for more information. |

### Experimental CSP Allow List

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 `experimentalCspAllowList` is `false`. 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
`experimentalCspAllowList` option to `true`. This will allow all CSP headers to
be sent to the browser _*except*_ those that could prevent Cypress from
functioning normally. The following CSP directives are automatically stripped
from the CSP headers when `experimentalCspAllowList` is set to `true`:

| Stripped Directive | Allowable | Reason |
| ---------------------------- | --------- | ---------------------------------------------------------------- |
| `default-src` | Yes | Conditionally prevents Cypress from loading scripts and running. |
| `frame-ancestors` | No | Prevents Cypress from loading a test application into an iframe. |
| `require-trusted-types-for`, | No | Might prevent Cypress from rewriting the DOM. |
| `sandbox` | Yes | Can restrict access to script and iframe functionality. |
| `form-action` | Yes | Can prevent Cypress from monitoring form events. |
| `navigate-to` | Yes | Affects Cypress' ability to navigate to different URLs. |
| `script-src` | Yes | Conditionally prevents Cypress from loading scripts and running. |
| `script-src-elem` | Yes | Conditionally prevents Cypress from loading scripts and running. |
| `trusted-types` | No | Could cause Cypress injections to be marked as untrusted. |

#### Allow Specific CSP Directives

If you need to test your application with CSP enabled, and need to test against
certain stripped CSP directives, you can set the `experimentalCspAllowList`
option to an array of directive names. This will allow the specified CSP
directives to be sent to the browser _so long as_ those those directives are
maked as "Allowable". You can find the "Allowable" status of each directive in
[the table above](#Strip-Minimum-CSP-Directives).

:::caution

Defining `experimentalCspAllowList` _*may*_ cause Cypress to be unable to run
tests against your application. This may be desired if you are testing against
specific CSP directives.

:::

## Testing Type-Specific Experiments

You can provide configuration options for either E2E or Component Testing by
Expand Down

0 comments on commit 7a50b35

Please sign in to comment.