> ## Documentation Index
> Fetch the complete documentation index at: https://site.aspect.build/llms.txt
> Use this file to discover all available pages before exploring further.

# @aspect_rules_cypress//cypress:defs.bzl

> Bazel rules_cypress public API reference: cypress_test macro and re-exports for running Cypress end-to-end JavaScript tests under Bazel with rules_js.

<Callout icon="book">
  Documentation for [@aspect\_rules\_cypress@v0.7.2](https://registry.bazel.build/modules/aspect_rules_cypress/0.7.2) -- <Icon icon="github" iconType="brands" /> [View source](https://github.com/aspect-build/rules_cypress/blob/v0.7.2/cypress/defs.bzl)
</Callout>

Public API re-exports

## Function: `cypress_test`

cypress\_test runs the cypress CLI with the cypress toolchain.

The environment is bootstrapped by first setting the environment variable `CYPRESS_RUN_BINARY` to the binary downloaded by the cypress toolchain. See [https://docs.cypress.io/guides/references/advanced-installation#Run-binary](https://docs.cypress.io/guides/references/advanced-installation#Run-binary)

See documentation on what arguments the cypress CLI supports:
[https://docs.cypress.io/guides/guides/command-line#What-you-ll-learn](https://docs.cypress.io/guides/guides/command-line#What-you-ll-learn)

### Parameters

<ParamField body="name" type="unknown" required>
  The name used for this rule and output files
</ParamField>

<ParamField body="cypress" type="unknown" default={`//:node_modules/cypress`}>
  The cypress npm package which was already linked using an API like npm\_link\_all\_packages.
</ParamField>

<ParamField body="disable_sandbox" type="unknown" default={`True`}>
  Turn off sandboxing by default to allow electron to perform write operations.
  Cypress does not expose the underlying electron apis so we
  cannot alter the user app data directory to be within the bazel
  sandbox.

  From [https://www.electronjs.org/docs/latest/api/app](https://www.electronjs.org/docs/latest/api/app)
  appData Per-user application data directory, which by default points to:
  %APPDATA% on Windows
  \$XDG\_CONFIG\_HOME or \~/.config on Linux
  \~/Library/Application Support on macOS

  Cypress may fail to connect on macos with errors like:
  Timed out waiting for the browser to connect. Retrying...
  Timed out waiting for the browser to connect. Retrying again...
  The browser never connected. Something is wrong. The tests cannot run. Aborting...
</ParamField>

<ParamField body="browsers" type="unknown" default={`[]`}>
  A sequence of labels specifying the browsers to include.
  Usually, any dependency that you wish to be included in the runfiles tree should
  be included within the data attribute. However, data dependencies, by default,
  are copied to the Bazel output tree before being passed as inputs to runfiles.

  This is not a good default behavior for browser since these typically come from
  external workspaces which cannot be symlinked into bazel-bin. Instead, we
  place them at the root of the runfiles tree. Use relative paths to construct
  account for this placement

  e.g. ../../../BROWSER\_WORKSPACE\_NAME
</ParamField>

<ParamField body="kwargs" type="unknown">
  All other args from `js_test`. See [https://github.com/aspect-build/rules\_js/blob/main/docs/js\_binary.md#js\_test](https://github.com/aspect-build/rules_js/blob/main/docs/js_binary.md#js_test)
</ParamField>

## Function: `cypress_module_test`

cypress\_module\_test creates a node environment which is hooked up to the cypress toolchain.

The environment is bootstrapped by first setting the environment variable `CYPRESS_RUN_BINARY` to the binary downloaded by the cypress toolchain. See [https://docs.cypress.io/guides/references/advanced-installation#Run-binary](https://docs.cypress.io/guides/references/advanced-installation#Run-binary)

You will provide a test runner, via the runner attribute, which is expected to call into cypress's module API to bootstrap testing.

Example `runner.js`:

```
async function main() {
const result = await cypress.run({
    headless: true,
});

// If any tests have failed, results.failures is non-zero, some tests have failed
if (result.failures) {
    console.error("One or more cypress tests have failed");
    console.error(result.message);
    return 1;
}

if (result.status === "failed") {
    console.log("Cypress exited with a failure status");
    return 2;
}

return 0;
}
```

In most scenarios, it is easier to use cypress\_test. But in some scenarios, you may need more flexibility:

* Accessing to the test results directly after the run and do something with them.
* Reruning a failing spec file
* Kicking off other builds or scripts

### Parameters

<ParamField body="name" type="unknown" required>
  The name used for this rule and output files
</ParamField>

<ParamField body="runner" type="unknown" required>
  JS file to call into the cypress module api
  See [https://docs.cypress.io/guides/guides/module-api](https://docs.cypress.io/guides/guides/module-api)
</ParamField>

<ParamField body="cypress" type="unknown" default={`//:node_modules/cypress`}>
  The cypress npm package which was already linked using an API like npm\_link\_all\_packages.
</ParamField>

<ParamField body="disable_sandbox" type="unknown" default={`True`}>
  Turn off sandboxing by default to allow electron to perform write operations.
  Cypress does not expose the underlying electron apis so we
  cannot alter the user app data directory to be within the bazel
  sandbox.

  From [https://www.electronjs.org/docs/latest/api/app](https://www.electronjs.org/docs/latest/api/app)
  appData Per-user application data directory, which by default points to:
  %APPDATA% on Windows
  \$XDG\_CONFIG\_HOME or \~/.config on Linux
  \~/Library/Application Support on macOS

  Cypress may fail to connect on macos with errors like:
  Timed out waiting for the browser to connect. Retrying...
  Timed out waiting for the browser to connect. Retrying again...
  The browser never connected. Something is wrong. The tests cannot run. Aborting...
</ParamField>

<ParamField body="browsers" type="unknown" default={`[]`}>
  A sequence of labels specifying the browsers to include.
  Usually, any dependency that you wish to be included in the runfiles tree should
  be included within the data attribute. However, data dependencies, by default,
  are copied to the Bazel output tree before being passed as inputs to runfiles.

  This is not a good default behavior for browser since these typically come from
  external workspaces which cannot be symlinked into bazel-bin. Instead, we
  place them at the root of the runfiles tree. Use relative paths to construct
  account for this placement

  e.g. ../../../BROWSER\_WORKSPACE\_NAME
</ParamField>

<ParamField body="kwargs" type="unknown">
  All other args from `js_test`. See [https://github.com/aspect-build/rules\_js/blob/main/docs/js\_binary.md#js\_test](https://github.com/aspect-build/rules_js/blob/main/docs/js_binary.md#js_test)
</ParamField>