From 6c65949b6d703d119381f12ae3df9c2411ff3f78 Mon Sep 17 00:00:00 2001 From: Alex Eagle Date: Mon, 27 Jul 2020 08:41:24 -0700 Subject: [PATCH] docs: add missing Cypress to leftnav (#2082) Also - fix link to my Bazel Leaving Labs post - don't point to generated API doc for angular/bazel package as that makes leftnav confusing - add some more explanation to Angular/React tradeoffs section --- docs/BUILD.bazel | 1 + docs/Cypress.md | 128 +++++++++++++++++++++++++++++++++++++ docs/_includes/drawer.html | 3 +- docs/examples.md | 21 ++++-- 4 files changed, 147 insertions(+), 6 deletions(-) create mode 100755 docs/Cypress.md diff --git a/docs/BUILD.bazel b/docs/BUILD.bazel index a0a7cd2797..eb16ffe8b8 100644 --- a/docs/BUILD.bazel +++ b/docs/BUILD.bazel @@ -55,6 +55,7 @@ genrule( _PACKAGE_READMES = { "Built-ins": ":builtins.doc", + "Cypress": "//packages/cypress:README.md", "Jasmine": "//packages/jasmine:README.md", "Karma": "//packages/karma:README.md", "Protractor": "//packages/protractor:README.md", diff --git a/docs/Cypress.md b/docs/Cypress.md new file mode 100755 index 0000000000..18d143db7c --- /dev/null +++ b/docs/Cypress.md @@ -0,0 +1,128 @@ +--- +title: Cypress +layout: default +stylesheet: docs +--- + +# Cypress rules for Bazel + +The Cypress rules run tests under the Cypress e2e testing framework with Bazel. + + +## Installation + +Add `@bazel/cypress`, `cypress` and `@cypress/browserify-preprocessor` npm packages to your `devDependencies` in `package.json`. + +``` +npm install --save-dev @bazel/cypress cypress @cypress/browserify-preprocessor +``` +or using yarn +``` +yarn add -D @bazel/cypress cypress @cypress/browserify-preprocessor +``` + +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", +) +```[name]: https://bazel.build/docs/build-ref.html#name +[label]: https://bazel.build/docs/build-ref.html#labels +[labels]: https://bazel.build/docs/build-ref.html#labels + + +## cypress_repository + + + + +### Usage + +``` +cypress_repository(name, cypress_bin, quiet) +``` + + + +#### `name` +(*[name], mandatory*): A unique name for this repository. + +#### `cypress_bin` +(*[label]*): bazel target of the cypress binary + +Defaults to `@npm//:node_modules/cypress/bin/cypress` + +#### `quiet` +(*Boolean*): If stdout and stderr should be printed to the terminal + +Defaults to `True` + diff --git a/docs/_includes/drawer.html b/docs/_includes/drawer.html index da735caa5e..67065e5928 100644 --- a/docs/_includes/drawer.html +++ b/docs/_includes/drawer.html @@ -41,12 +41,13 @@
  • Frameworks
  • Testing