docs/Cypress.md

---
title: Cypress
layout: default
toc: true
nav: rule
---
<!-- *********************
  DO NOT EDIT THIS FILE
  It is a generated build output from Stardoc.
  Instead you must edit the .bzl file where the rules are declared,
  or possibly a markdown file next to the .bzl file
 ********************* -->

# Cypress rules for Bazel

The Cypress rules run tests under the Cypress e2e testing framework with Bazel.

## Installation

Add `@bazel/cypress` and `cypress` npm packages to your `devDependencies` in `package.json`.

```
npm install --save-dev @bazel/cypress cypress
```
or using yarn
```
yarn add -D @bazel/cypress cypress
```

Then, load and invoke `cypress_repository` within your `WORKSPACE` file.

```python
# Assuming your external repository for node_modules is named @npm

load("@npm//@bazel/cypress:index.bzl", "cypress_repository")

# The name you pass here names the external repository you can load cypress_web_test from
cypress_repository(name = "cypress")
```

### macOS install requirements
On macOS, `cypress_repository` generates an external repository containing files whose names contain spaces. In order to make these files compatible with bazel you will need to add the following flag to your `.bazelrc` file:
```python
# Required for cypress_repository on macOS
build --experimental_inprocess_symlink_creation
```

### windows install requirements
At this point in time, `cypress_repository` is incompatible with bazel sandboxing on Windows. This may change in the future, but for now using cypress on windows requires windows sandboxing be disabled (it is disabled by default)

## Example use of cypress_web_test
This example assumes you've named your external repository for node_modules as `npm` and for cypress as `cypress`
```python
load("@cypress//:index.bzl", "cypress_web_test")
load("@npm//@bazel/typescript:index.bzl", "ts_library")

# You must create a cypress plugin in order to boot a server to serve your application. It can be written as a javascript file or in typescript using ts_library or ts_project.
ts_library(
    name = "plugins_file",
    testonly = True,
    srcs = ["plugin.ts"],
    tsconfig = ":tsconfig.json",
    deps = [
        "@npm//@types/node",
        "@npm//express",
    ],
)

# You can write your cypress tests a javascript files or in typescript using ts_library or ts_project.
ts_library(
    name = "hello_spec",
    testonly = True,
    srcs = ["hello.spec.ts"],
    tsconfig = ":tsconfig.json",
    deps = [
        "@npm//cypress",
    ],
)

cypress_web_test(
    # The name of your test target
    name = "test",
    srcs = [
        # Load javascript test files directly as sources
        "world.spec.js",
        # Load ts_library tests as a target to srcs
        ":hello_spec",
    ],
    # A cypress config file is required
    config_file = "cypress.json",
    # Any runtime dependencies you need to boot your server or run your tests
    data = [],
    # Your cypress plugin used to configure cypress and boot your server
    plugins_file = ":plugins_file",
)
```


## cypress_repository

**USAGE**

<pre>
cypress_repository(<a href="#cypress_repository-name">name</a>, <a href="#cypress_repository-cypress_bin">cypress_bin</a>, <a href="#cypress_repository-fail_on_error">fail_on_error</a>, <a href="#cypress_repository-quiet">quiet</a>, <a href="#cypress_repository-repo_mapping">repo_mapping</a>)
</pre>



**ATTRIBUTES**


<h4 id="cypress_repository-name">name</h4>

(*<a href="https://bazel.build/docs/build-ref.html#name">Name</a>, mandatory*): A unique name for this repository.


<h4 id="cypress_repository-cypress_bin">cypress_bin</h4>

(*<a href="https://bazel.build/docs/build-ref.html#labels">Label</a>*): bazel target of the cypress binary

Defaults to `@npm//:node_modules/cypress/bin/cypress`

<h4 id="cypress_repository-fail_on_error">fail_on_error</h4>

(*Boolean*): If the repository rule should allow errors

Defaults to `True`

<h4 id="cypress_repository-quiet">quiet</h4>

(*Boolean*): If stdout and stderr should be printed to the terminal

Defaults to `True`

<h4 id="cypress_repository-repo_mapping">repo_mapping</h4>

(*<a href="https://bazel.build/docs/skylark/lib/dict.html">Dictionary: String -> String</a>, mandatory*): A dictionary from local repository name to global repository name. This allows controls over workspace dependency resolution for dependencies of this repository.<p>For example, an entry `"@foo": "@bar"` declares that, for any time this repository depends on `@foo` (such as a dependency on `@foo//some:target`, it should actually resolve that dependency within globally-declared `@bar` (`@bar//some:target`).