blob: 6b2114ec53ce8caa0ab27a2c8a1aed6b9c12e5df [file] [log] [blame] [view] [edit]
---
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`).