Add docs for karma rules Closes #417 PiperOrigin-RevId: 233688614
diff --git a/DEVELOPING.md b/DEVELOPING.md index f45639b..81bc6e1 100644 --- a/DEVELOPING.md +++ b/DEVELOPING.md
@@ -56,14 +56,14 @@ (This may not sound like semver - but since our major version is a zero, the rule is that minors are breaking changes and patches are new features). -1. Re-generate the API docs: `yarn skydoc` +1. Re-generate the API docs: `yarn skydoc && (cd internal/karma; yarn skydoc)` 1. May be necessary if Go code has changed though probably it was already necessary to run this to keep CI green: `bazel run :gazelle` 1. If we depend on a newer rules_nodejs, update the `check_rules_nodejs_version` in `ts_repositories.bzl` 1. `git commit -a -m 'Update docs for release'` 1. `npm config set tag-version-prefix ''` 1. `npm version minor -m 'rel: %s'` (replace `minor` with `patch` if no breaking changes) -1. Build npm packages and publish them: `TMP=$(mktemp -d -t bazel-release.XXXXXXX); bazel --output_base=$TMP run //:npm_package.publish && cd internal/karma && bazel --output_base=$TMP run //:npm_package.publish` -1. `git push && git push --tags` +1. Build npm packages and publish them: `TMP=$(mktemp -d -t bazel-release.XXXXXXX); bazel --output_base=$TMP run //:npm_package.publish && ( cd internal/karma && bazel --output_base=$TMP run //:npm_package.publish )` +1. `git push upstream && git push upstream --tags` (assumes you named the bazelbuild fork as "upstream") 1. (Temporary): submit a google3 CL to update the versions in package.bzl and package.json [releases]: https://github.com/bazelbuild/rules_typescript/releases
diff --git a/README.md b/README.md index 736956d..b404de8 100644 --- a/README.md +++ b/README.md
@@ -8,6 +8,9 @@ The TypeScript rules integrate the TypeScript compiler with Bazel. +This repo used to contain Karma rules `ts_web_test` and `karma_web_test`. +These are now documented in the README at http://npmjs.com/package/@bazel/karma + ## API Docs Generated documentation for using each rule is at: @@ -18,15 +21,12 @@ First, install a current Bazel distribution. Add the `@bazel/typescript` npm package to your `package.json` `devDependencies`. -Optionally add the `@bazel/karma` npm package if you would like to use the -`ts_web_test`, `ts_web_test_suite`, `karma_web_test` or `karma_web_test_suite` rules. ``` { ... "devDependencies": { "@bazel/typescript": "0.25.0", - "@bazel/karma": "0.25.0", ... }, ... @@ -59,7 +59,7 @@ node_repositories() # Setup Bazel managed npm dependencies with the `yarn_install` rule. -# The name of this rule should be set to `npm` so that `ts_library` and `ts_web_test_suite` +# The name of this rule should be set to `npm` so that `ts_library` # can find your npm dependencies by default in the `@npm` workspace. You may # also use the `npm_install` rule with a `package-lock.json` file if you prefer. # See https://github.com/bazelbuild/rules_nodejs#dependencies for more info. @@ -73,23 +73,9 @@ load("@npm//:install_bazel_dependencies.bzl", "install_bazel_dependencies") install_bazel_dependencies() -# Fetch transitive Bazel dependencies of npm_bazel_karma -# ONLY REQUIRED if you are using the @bazel/karma npm package -load("@npm_bazel_karma//:package.bzl", "rules_karma_dependencies") -rules_karma_dependencies() - # Setup TypeScript toolchain load("@npm_bazel_typescript//:defs.bzl", "ts_setup_workspace") ts_setup_workspace() - -# Setup web testing, choose browsers we can test on -# ONLY REQUIRED if you are using the @bazel/karma npm package -load("@io_bazel_rules_webtesting//web:repositories.bzl", "browser_repositories", "web_test_repositories") - -web_test_repositories() -browser_repositories( - chromium = True, -) ``` # Self-managed npm dependencies @@ -143,15 +129,6 @@ # Point bazel to your node_modules to find the entry point node_modules = ["//:node_modules"], ) - -# Create a karma rule to use in ts_web_test_suite karma -# attribute when using self-managed dependencies -nodejs_binary( - name = "karma/karma", - entry_point = "karma/bin/karma", - # Point bazel to your node_modules to find the entry point - node_modules = ["//:node_modules"], -) ``` See https://github.com/bazelbuild/rules_nodejs#dependencies for more information on @@ -325,7 +302,4 @@ At some point, we plan to release a tool similar to [gazelle] to generate the BUILD files from your source code. -In the meantime, we suggest associating the `.bazel` extension with Python in -your editor, so that you get useful syntax highlighting. - [gazelle]: https://github.com/bazelbuild/rules_go/tree/master/go/tools/gazelle
diff --git a/docs/BUILD.bazel b/docs/BUILD.bazel index edd7143..019f3dc 100644 --- a/docs/BUILD.bazel +++ b/docs/BUILD.bazel
@@ -8,9 +8,6 @@ "//internal:ts_repositories.bzl", "//internal/devserver:ts_devserver.bzl", "//internal/protobufjs:ts_proto_library.bzl", - # TODO(gregmagolan): fix docs for npm_bazel_karma - # "@npm_bazel_karma//:karma_web_test.bzl", - # "@npm_bazel_karma//:ts_web_test.bzl", ], format = "html", # The site is served at http://tsetse.info so the URL doesn't include a
diff --git a/internal/karma/.gitignore b/internal/karma/.gitignore new file mode 100644 index 0000000..bae2b58 --- /dev/null +++ b/internal/karma/.gitignore
@@ -0,0 +1,2 @@ +# This file is generated during the build +README.md
diff --git a/internal/karma/WORKSPACE b/internal/karma/WORKSPACE index a2a3401..f584c27 100644 --- a/internal/karma/WORKSPACE +++ b/internal/karma/WORKSPACE
@@ -43,12 +43,27 @@ yarn_lock = "//:yarn.lock", ) -# Setup gazelle toolchain -load("@bazel_gazelle//:deps.bzl", "gazelle_dependencies") - -gazelle_dependencies() - # Setup typescript toolchain load("@npm_bazel_typescript//:defs.bzl", "ts_setup_workspace") ts_setup_workspace() + +# Dependencies for generating documentation +load("@io_bazel_rules_sass//sass:sass_repositories.bzl", "sass_repositories") + +sass_repositories() + +load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive") + +http_archive( + name = "com_google_protobuf", + strip_prefix = "protobuf-3.6.1.3", + sha256 = "9510dd2afc29e7245e9e884336f848c8a6600a14ae726adb6befdb4f786f0be2", + # v3.6.1.3 as of 2019-01-15 + urls = ["https://github.com/protocolbuffers/protobuf/archive/v3.6.1.3.zip"], + type = "zip", +) + +load("@io_bazel_skydoc//skylark:skylark.bzl", "skydoc_repositories") + +skydoc_repositories()
diff --git a/internal/karma/docs/BUILD.bazel b/internal/karma/docs/BUILD.bazel new file mode 100644 index 0000000..dc0a3bc --- /dev/null +++ b/internal/karma/docs/BUILD.bazel
@@ -0,0 +1,10 @@ +load("@io_bazel_skydoc//skylark:skylark.bzl", "skylark_doc") + +skylark_doc( + name = "docs", + srcs = [ + "//:karma_web_test.bzl", + "//:ts_web_test.bzl", + ], + format = "markdown", +)
diff --git a/internal/karma/docs/index.md b/internal/karma/docs/index.md new file mode 100644 index 0000000..697f82f --- /dev/null +++ b/internal/karma/docs/index.md
@@ -0,0 +1,89 @@ + +# Overview + + +<nav class="toc"> + <h2>Rule sets</h2> + <ul> + <li><a href="#karma_web_test">Unit testing with Karma</a></li> + <li><a href="#ts_web_test">Unit testing in a browser</a></li> + </ul> +</nav> + +<h2><a href="/karma_web_test.html" id="karma_web_test">Unit testing with Karma</a></h2> + +<h3>Macros</h3> +<table class="overview-table"> + <colgroup> + <col class="col-name" /> + <col class="col-description" /> + </colgroup> + <tbody> + <tr> + <td> + <a href="/karma_web_test.html#run_karma_web_test"> + <code>run_karma_web_test</code> + </a> + </td> + <td> + <p>Creates an action that can run karma.</p> + + </td> + </tr> + <tr> + <td> + <a href="/karma_web_test.html#karma_web_test"> + <code>karma_web_test</code> + </a> + </td> + <td> + <p>Runs unit tests in a browser with Karma.</p> + + </td> + </tr> + <tr> + <td> + <a href="/karma_web_test.html#karma_web_test_suite"> + <code>karma_web_test_suite</code> + </a> + </td> + <td> + <p>Defines a test_suite of web_test targets that wrap a karma_web_test target.</p> + + </td> + </tr> + </tbody> +</table> +<h2><a href="/ts_web_test.html" id="ts_web_test">Unit testing in a browser</a></h2> + +<h3>Macros</h3> +<table class="overview-table"> + <colgroup> + <col class="col-name" /> + <col class="col-description" /> + </colgroup> + <tbody> + <tr> + <td> + <a href="/ts_web_test.html#ts_web_test"> + <code>ts_web_test</code> + </a> + </td> + <td> + <p>Runs unit tests in a browser.</p> + + </td> + </tr> + <tr> + <td> + <a href="/ts_web_test.html#ts_web_test_suite"> + <code>ts_web_test_suite</code> + </a> + </td> + <td> + <p>Defines a test_suite of web_test targets that wrap a ts_web_test target.</p> + + </td> + </tr> + </tbody> +</table>
diff --git a/internal/karma/docs/install.md b/internal/karma/docs/install.md new file mode 100644 index 0000000..e04b558 --- /dev/null +++ b/internal/karma/docs/install.md
@@ -0,0 +1,80 @@ +# Karma rules for Bazel + +**WARNING: this is beta-quality software. Breaking changes are likely. Not recommended for production use without expert support.** + +The Karma rules run karma tests with Bazel. + +## Installation + +Add the `@bazel/karma` npm package to your `devDependencies` in `package.json`. + +Your `WORKSPACE` should declare a `yarn_install` or `npm_install` rule named `npm`. +It should then install the rules found in the npm packages. + +This is copied from the README for rules_nodejs: + +```python +load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive") + +# Fetch rules_nodejs +# (you can check https://github.com/bazelbuild/rules_nodejs/releases for a newer release than this) +http_archive( + name = "build_bazel_rules_nodejs", + urls = ["https://github.com/bazelbuild/rules_nodejs/releases/download/0.18.5/rules_nodejs-0.18.5.tar.gz"], + sha256 = "c8cd6a77433f7d3bb1f4ac87f15822aa102989f8e9eb1907ca0cad718573985b", +) + +# Setup the NodeJS toolchain +load("@build_bazel_rules_nodejs//:defs.bzl", "node_repositories", "yarn_install") +node_repositories() + +yarn_install( + name = "npm", + package_json = "//:package.json", + yarn_lock = "//:yarn.lock", +) + +# Install all Bazel dependencies needed for npm packages that supply Bazel rules +load("@npm//:install_bazel_dependencies.bzl", "install_bazel_dependencies") +install_bazel_dependencies() +``` + +This causes the `@bazel/karma` package to be installed as a Bazel workspace named `npm_bazel_karma`. + +Now add this to your `WORKSPACE` to install the Karma dependencies: + +```python +# Fetch transitive Bazel dependencies of npm_bazel_karma +load("@npm_bazel_karma//:package.bzl", "rules_karma_dependencies") +rules_karma_dependencies() +``` + +This installs the `io_bazel_rules_webtesting` repository, if you haven't installed it earlier. + +Finally, configure the rules_webtesting: + +```python +# Setup web testing, choose browsers we can test on +load("@io_bazel_rules_webtesting//web:repositories.bzl", "browser_repositories", "web_test_repositories") + +web_test_repositories() +browser_repositories( + chromium = True, +) +``` + +## Installing with self-managed dependencies + +If you didn't use the `yarn_install` or `npm_install` rule to create an `npm` workspace, you'll have to declare a rule in your root `BUILD.bazel` file to execute karma: + +```python +# Create a karma rule to use in ts_web_test_suite karma +# attribute when using self-managed dependencies +nodejs_binary( + name = "karma/karma", + entry_point = "karma/bin/karma", + # Point bazel to your node_modules to find the entry point + node_modules = ["//:node_modules"], +) +``` +
diff --git a/internal/karma/docs/karma_web_test.md b/internal/karma/docs/karma_web_test.md new file mode 100644 index 0000000..39c6543 --- /dev/null +++ b/internal/karma/docs/karma_web_test.md
@@ -0,0 +1,315 @@ + +<!--- +Documentation generated by Skydoc +--> +<h1>Unit testing with Karma</h1> + + +<nav class="toc"> + <h2>Macros</h2> + <ul> + <li><a href="#run_karma_web_test">run_karma_web_test</a></li> + <li><a href="#karma_web_test">karma_web_test</a></li> + <li><a href="#karma_web_test_suite">karma_web_test_suite</a></li> + </ul> +</nav> +<a name="run_karma_web_test"></a> +## run_karma_web_test + +<pre> +run_karma_web_test(<a href="#run_karma_web_test.ctx">ctx</a>) +</pre> + +Creates an action that can run karma. + +This is also used by ts_web_test_rule. + +Returns: + The runfiles for the generated action. + + +<a name="run_karma_web_test_args"></a> +### Attributes + + +<table class="params-table"> + <colgroup> + <col class="col-param" /> + <col class="col-description" /> + </colgroup> + <tbody> + <tr id="run_karma_web_test.ctx"> + <td><code>ctx</code></td> + <td> + <p><code>Unknown; Required</code></p> + <p>Bazel rule execution context</p> + </td> + </tr> + </tbody> +</table> +<a name="karma_web_test"></a> +## karma_web_test + +<pre> +karma_web_test(<a href="#karma_web_test.srcs">srcs</a>, <a href="#karma_web_test.deps">deps</a>, <a href="#karma_web_test.data">data</a>, <a href="#karma_web_test.configuration_env_vars">configuration_env_vars</a>, <a href="#karma_web_test.bootstrap">bootstrap</a>, <a href="#karma_web_test.runtime_deps">runtime_deps</a>, <a href="#karma_web_test.static_files">static_files</a>, <a href="#karma_web_test.config_file">config_file</a>, <a href="#karma_web_test.tags">tags</a>, <a href="#karma_web_test.**kwargs">**kwargs</a>) +</pre> + +Runs unit tests in a browser with Karma. + +When executed under `bazel test`, this uses a headless browser for speed. +This is also because `bazel test` allows multiple targets to be tested together, +and we don't want to open a Chrome window on your machine for each one. Also, +under `bazel test` the test will execute and immediately terminate. + +Running under `ibazel test` gives you a "watch mode" for your tests. The rule is +optimized for this case - the test runner server will stay running and just +re-serve the up-to-date JavaScript source bundle. + +To debug a single test target, run it with `bazel run` instead. This will open a +browser window on your computer. Also you can use any other browser by opening +the URL printed when the test starts up. The test will remain running until you +cancel the `bazel run` command. + +This rule will use your system Chrome by default. In the default case, your +environment must specify CHROME_BIN so that the rule will know which Chrome binary to run. +Other `browsers` and `customLaunchers` may be set using the a base Karma configuration +specified in the `config_file` attribute. + + +<a name="karma_web_test_args"></a> +### Attributes + + +<table class="params-table"> + <colgroup> + <col class="col-param" /> + <col class="col-description" /> + </colgroup> + <tbody> + <tr id="karma_web_test.srcs"> + <td><code>srcs</code></td> + <td> + <p><code>List of strings; Optional</code></p> + <p>A list of JavaScript test files</p> + </td> + </tr> + <tr id="karma_web_test.deps"> + <td><code>deps</code></td> + <td> + <p><code>List of strings; Optional</code></p> + <p>Other targets which produce JavaScript such as <code>ts_library</code></p> + </td> + </tr> + <tr id="karma_web_test.data"> + <td><code>data</code></td> + <td> + <p><code>List of strings; Optional</code></p> + <p>Runtime dependencies</p> + </td> + </tr> + <tr id="karma_web_test.configuration_env_vars"> + <td><code>configuration_env_vars</code></td> + <td> + <p><code>List of strings; Optional</code></p> + <p>Pass these configuration environment variables to the resulting binary. +Chooses a subset of the configuration environment variables (taken from ctx.var), which also +includes anything specified via the --define flag. +Note, this can lead to different outputs produced by this rule.</p> + </td> + </tr> + <tr id="karma_web_test.bootstrap"> + <td><code>bootstrap</code></td> + <td> + <p><code>List of strings; Optional</code></p> + <p>JavaScript files to include <em>before</em> the module loader (require.js). +For example, you can include Reflect,js for TypeScript decorator metadata reflection, +or UMD bundles for third-party libraries.</p> + </td> + </tr> + <tr id="karma_web_test.runtime_deps"> + <td><code>runtime_deps</code></td> + <td> + <p><code>List of strings; Optional</code></p> + <p>Dependencies which should be loaded after the module loader but before the srcs and deps. +These should be a list of targets which produce JavaScript such as <code>ts_library</code>. +The files will be loaded in the same order they are declared by that rule.</p> + </td> + </tr> + <tr id="karma_web_test.static_files"> + <td><code>static_files</code></td> + <td> + <p><code>List of strings; Optional</code></p> + <p>Arbitrary files which are available to be served on request. +Files are served at: +<code>/base/&lt;WORKSPACE_NAME&gt;/&lt;path-to-file&gt;</code>, e.g. +<code>/base/npm_bazel_typescript/examples/testing/static_script.js</code></p> + </td> + </tr> + <tr id="karma_web_test.config_file"> + <td><code>config_file</code></td> + <td> + <p><code>Unknown; Optional</code></p> + <p>User supplied Karma configuration file. Bazel will override +certain attributes of this configuration file. Attributes that are +overridden will be outputted to the test log.</p> + </td> + </tr> + <tr id="karma_web_test.tags"> + <td><code>tags</code></td> + <td> + <p><code>List of strings; Optional</code></p> + <p>Standard Bazel tags, this macro adds tags for ibazel support</p> + </td> + </tr> + <tr id="karma_web_test.**kwargs"> + <td><code>**kwargs</code></td> + <td> + <p><code>Unknown; Optional</code></p> + <p>Passed through to <code>karma_web_test</code></p> + </td> + </tr> + </tbody> +</table> +<a name="karma_web_test_suite"></a> +## karma_web_test_suite + +<pre> +karma_web_test_suite(<a href="#karma_web_test_suite.name">name</a>, <a href="#karma_web_test_suite.browsers">browsers</a>, <a href="#karma_web_test_suite.args">args</a>, <a href="#karma_web_test_suite.browser_overrides">browser_overrides</a>, <a href="#karma_web_test_suite.config">config</a>, <a href="#karma_web_test_suite.flaky">flaky</a>, <a href="#karma_web_test_suite.local">local</a>, <a href="#karma_web_test_suite.shard_count">shard_count</a>, <a href="#karma_web_test_suite.size">size</a>, <a href="#karma_web_test_suite.tags">tags</a>, <a href="#karma_web_test_suite.test_suite_tags">test_suite_tags</a>, <a href="#karma_web_test_suite.timeout">timeout</a>, <a href="#karma_web_test_suite.visibility">visibility</a>, <a href="#karma_web_test_suite.web_test_data">web_test_data</a>, <a href="#karma_web_test_suite.wrapped_test_tags">wrapped_test_tags</a>, <a href="#karma_web_test_suite.**remaining_keyword_args">**remaining_keyword_args</a>) +</pre> + +Defines a test_suite of web_test targets that wrap a karma_web_test target. + +This macro also accepts all parameters in karma_web_test. See karma_web_test docs +for details. + + +<a name="karma_web_test_suite_args"></a> +### Attributes + + +<table class="params-table"> + <colgroup> + <col class="col-param" /> + <col class="col-description" /> + </colgroup> + <tbody> + <tr id="karma_web_test_suite.name"> + <td><code>name</code></td> + <td> + <p><code><a href="https://bazel.build/docs/build-ref.html#name">Name</a>; Required</code></p> + <p>The base name of the test</p> + </td> + </tr> + <tr id="karma_web_test_suite.browsers"> + <td><code>browsers</code></td> + <td> + <p><code>List of strings; Optional</code></p> + <p>A sequence of labels specifying the browsers to use.</p> + </td> + </tr> + <tr id="karma_web_test_suite.args"> + <td><code>args</code></td> + <td> + <p><code>Unknown; Optional</code></p> + <p>Args for web_test targets generated by this extension.</p> + </td> + </tr> + <tr id="karma_web_test_suite.browser_overrides"> + <td><code>browser_overrides</code></td> + <td> + <p><code>Unknown; Optional</code></p> + <p>Dictionary; optional; default is an empty dictionary. A +dictionary mapping from browser names to browser-specific web_test +attributes, such as shard_count, flakiness, timeout, etc. For example: +{'//browsers:chrome-native': {'shard_count': 3, 'flaky': 1} +'//browsers:firefox-native': {'shard_count': 1, 'timeout': 100}}.</p> + </td> + </tr> + <tr id="karma_web_test_suite.config"> + <td><code>config</code></td> + <td> + <p><code>Unknown; Optional</code></p> + <p>Label; optional; Configuration of web test features.</p> + </td> + </tr> + <tr id="karma_web_test_suite.flaky"> + <td><code>flaky</code></td> + <td> + <p><code>Unknown; Optional</code></p> + <p>A boolean specifying that the test is flaky. If set, the test will +be retried up to 3 times (default: 0)</p> + </td> + </tr> + <tr id="karma_web_test_suite.local"> + <td><code>local</code></td> + <td> + <p><code>Unknown; Optional</code></p> + <p>boolean; optional.</p> + </td> + </tr> + <tr id="karma_web_test_suite.shard_count"> + <td><code>shard_count</code></td> + <td> + <p><code>Unknown; Optional</code></p> + <p>The number of test shards to use per browser. (default: 1)</p> + </td> + </tr> + <tr id="karma_web_test_suite.size"> + <td><code>size</code></td> + <td> + <p><code>Unknown; Optional</code></p> + <p>A string specifying the test size. (default: 'large')</p> + </td> + </tr> + <tr id="karma_web_test_suite.tags"> + <td><code>tags</code></td> + <td> + <p><code>List of strings; Optional</code></p> + <p>A list of test tag strings to apply to each generated web_test target. +This macro adds a couple for ibazel.</p> + </td> + </tr> + <tr id="karma_web_test_suite.test_suite_tags"> + <td><code>test_suite_tags</code></td> + <td> + <p><code>Unknown; Optional</code></p> + <p>A list of tag strings for the generated test_suite.</p> + </td> + </tr> + <tr id="karma_web_test_suite.timeout"> + <td><code>timeout</code></td> + <td> + <p><code>Unknown; Optional</code></p> + <p>A string specifying the test timeout (default: computed from size)</p> + </td> + </tr> + <tr id="karma_web_test_suite.visibility"> + <td><code>visibility</code></td> + <td> + <p><code>Unknown; Optional</code></p> + <p>List of labels; optional.</p> + </td> + </tr> + <tr id="karma_web_test_suite.web_test_data"> + <td><code>web_test_data</code></td> + <td> + <p><code>List of strings; Optional</code></p> + <p>Data dependencies for the web_test.</p> + </td> + </tr> + <tr id="karma_web_test_suite.wrapped_test_tags"> + <td><code>wrapped_test_tags</code></td> + <td> + <p><code>Unknown; Optional</code></p> + <p>A list of test tag strings to use for the wrapped test</p> + </td> + </tr> + <tr id="karma_web_test_suite.**remaining_keyword_args"> + <td><code>**remaining_keyword_args</code></td> + <td> + <p><code>Unknown; Optional</code></p> + <p>Arguments for the wrapped test target.</p> + </td> + </tr> + </tbody> +</table>
diff --git a/internal/karma/docs/ts_web_test.md b/internal/karma/docs/ts_web_test.md new file mode 100644 index 0000000..eca8535 --- /dev/null +++ b/internal/karma/docs/ts_web_test.md
@@ -0,0 +1,272 @@ + +<!--- +Documentation generated by Skydoc +--> +<h1>Unit testing in a browser</h1> + + +<nav class="toc"> + <h2>Macros</h2> + <ul> + <li><a href="#ts_web_test">ts_web_test</a></li> + <li><a href="#ts_web_test_suite">ts_web_test_suite</a></li> + </ul> +</nav> +<a name="ts_web_test"></a> +## ts_web_test + +<pre> +ts_web_test(<a href="#ts_web_test.srcs">srcs</a>, <a href="#ts_web_test.deps">deps</a>, <a href="#ts_web_test.data">data</a>, <a href="#ts_web_test.configuration_env_vars">configuration_env_vars</a>, <a href="#ts_web_test.bootstrap">bootstrap</a>, <a href="#ts_web_test.runtime_deps">runtime_deps</a>, <a href="#ts_web_test.static_files">static_files</a>, <a href="#ts_web_test.tags">tags</a>, <a href="#ts_web_test.**kwargs">**kwargs</a>) +</pre> + +Runs unit tests in a browser. + +When executed under `bazel test`, this uses a headless browser for speed. +This is also because `bazel test` allows multiple targets to be tested together, +and we don't want to open a Chrome window on your machine for each one. Also, +under `bazel test` the test will execute and immediately terminate. + +Running under `ibazel test` gives you a "watch mode" for your tests. The rule is +optimized for this case - the test runner server will stay running and just +re-serve the up-to-date JavaScript source bundle. + +To debug a single test target, run it with `bazel run` instead. This will open a +browser window on your computer. Also you can use any other browser by opening +the URL printed when the test starts up. The test will remain running until you +cancel the `bazel run` command. + +This rule will use your system Chrome. Your environment must specify CHROME_BIN +so that the rule will know which Chrome binary to run. + +Currently this rule uses Karma as the test runner under the hood, but this is +an implementation detail. We might switch to another runner like Jest in the future. + + +<a name="ts_web_test_args"></a> +### Attributes + + +<table class="params-table"> + <colgroup> + <col class="col-param" /> + <col class="col-description" /> + </colgroup> + <tbody> + <tr id="ts_web_test.srcs"> + <td><code>srcs</code></td> + <td> + <p><code>List of strings; Optional</code></p> + <p>A list of JavaScript test files</p> + </td> + </tr> + <tr id="ts_web_test.deps"> + <td><code>deps</code></td> + <td> + <p><code>List of strings; Optional</code></p> + <p>Other targets which produce JavaScript such as <code>ts_library</code></p> + </td> + </tr> + <tr id="ts_web_test.data"> + <td><code>data</code></td> + <td> + <p><code>List of strings; Optional</code></p> + <p>Runtime dependencies</p> + </td> + </tr> + <tr id="ts_web_test.configuration_env_vars"> + <td><code>configuration_env_vars</code></td> + <td> + <p><code>List of strings; Optional</code></p> + <p>Pass these configuration environment variables to the resulting binary. +Chooses a subset of the configuration environment variables (taken from ctx.var), which also +includes anything specified via the --define flag. +Note, this can lead to different outputs produced by this rule.</p> + </td> + </tr> + <tr id="ts_web_test.bootstrap"> + <td><code>bootstrap</code></td> + <td> + <p><code>List of strings; Optional</code></p> + <p>JavaScript files to include <em>before</em> the module loader (require.js). +For example, you can include Reflect,js for TypeScript decorator metadata reflection, +or UMD bundles for third-party libraries.</p> + </td> + </tr> + <tr id="ts_web_test.runtime_deps"> + <td><code>runtime_deps</code></td> + <td> + <p><code>List of strings; Optional</code></p> + <p>Dependencies which should be loaded after the module loader but before the srcs and deps. +These should be a list of targets which produce JavaScript such as <code>ts_library</code>. +The files will be loaded in the same order they are declared by that rule.</p> + </td> + </tr> + <tr id="ts_web_test.static_files"> + <td><code>static_files</code></td> + <td> + <p><code>List of strings; Optional</code></p> + <p>Arbitrary files which are available to be served on request. +Files are served at: +<code>/base/&lt;WORKSPACE_NAME&gt;/&lt;path-to-file&gt;</code>, e.g. +<code>/base/npm_bazel_typescript/examples/testing/static_script.js</code></p> + </td> + </tr> + <tr id="ts_web_test.tags"> + <td><code>tags</code></td> + <td> + <p><code>List of strings; Optional</code></p> + <p>Standard Bazel tags, this macro adds tags for ibazel support as well as</p> + </td> + </tr> + <tr id="ts_web_test.**kwargs"> + <td><code>**kwargs</code></td> + <td> + <p><code>Unknown; Optional</code></p> + <p>Passed through to <code>ts_web_test</code></p> + </td> + </tr> + </tbody> +</table> +<a name="ts_web_test_suite"></a> +## ts_web_test_suite + +<pre> +ts_web_test_suite(<a href="#ts_web_test_suite.name">name</a>, <a href="#ts_web_test_suite.browsers">browsers</a>, <a href="#ts_web_test_suite.args">args</a>, <a href="#ts_web_test_suite.browser_overrides">browser_overrides</a>, <a href="#ts_web_test_suite.config">config</a>, <a href="#ts_web_test_suite.flaky">flaky</a>, <a href="#ts_web_test_suite.local">local</a>, <a href="#ts_web_test_suite.shard_count">shard_count</a>, <a href="#ts_web_test_suite.size">size</a>, <a href="#ts_web_test_suite.tags">tags</a>, <a href="#ts_web_test_suite.test_suite_tags">test_suite_tags</a>, <a href="#ts_web_test_suite.timeout">timeout</a>, <a href="#ts_web_test_suite.visibility">visibility</a>, <a href="#ts_web_test_suite.web_test_data">web_test_data</a>, <a href="#ts_web_test_suite.wrapped_test_tags">wrapped_test_tags</a>, <a href="#ts_web_test_suite.**remaining_keyword_args">**remaining_keyword_args</a>) +</pre> + +Defines a test_suite of web_test targets that wrap a ts_web_test target. + +This macro also accepts all parameters in ts_web_test. See ts_web_test docs for +details. + + +<a name="ts_web_test_suite_args"></a> +### Attributes + + +<table class="params-table"> + <colgroup> + <col class="col-param" /> + <col class="col-description" /> + </colgroup> + <tbody> + <tr id="ts_web_test_suite.name"> + <td><code>name</code></td> + <td> + <p><code><a href="https://bazel.build/docs/build-ref.html#name">Name</a>; Required</code></p> + <p>The base name of the test.</p> + </td> + </tr> + <tr id="ts_web_test_suite.browsers"> + <td><code>browsers</code></td> + <td> + <p><code>List of strings; Optional</code></p> + <p>A sequence of labels specifying the browsers to use.</p> + </td> + </tr> + <tr id="ts_web_test_suite.args"> + <td><code>args</code></td> + <td> + <p><code>Unknown; Optional</code></p> + <p>Args for web_test targets generated by this extension.</p> + </td> + </tr> + <tr id="ts_web_test_suite.browser_overrides"> + <td><code>browser_overrides</code></td> + <td> + <p><code>Unknown; Optional</code></p> + <p>Dictionary; optional; default is an empty dictionary. A +dictionary mapping from browser names to browser-specific web_test +attributes, such as shard_count, flakiness, timeout, etc. For example: +{'//browsers:chrome-native': {'shard_count': 3, 'flaky': 1} +'//browsers:firefox-native': {'shard_count': 1, 'timeout': 100}}.</p> + </td> + </tr> + <tr id="ts_web_test_suite.config"> + <td><code>config</code></td> + <td> + <p><code>Unknown; Optional</code></p> + <p>Label; optional; Configuration of web test features.</p> + </td> + </tr> + <tr id="ts_web_test_suite.flaky"> + <td><code>flaky</code></td> + <td> + <p><code>Unknown; Optional</code></p> + <p>A boolean specifying that the test is flaky. If set, the test will +be retried up to 3 times (default: 0)</p> + </td> + </tr> + <tr id="ts_web_test_suite.local"> + <td><code>local</code></td> + <td> + <p><code>Unknown; Optional</code></p> + <p>boolean; optional.</p> + </td> + </tr> + <tr id="ts_web_test_suite.shard_count"> + <td><code>shard_count</code></td> + <td> + <p><code>Unknown; Optional</code></p> + <p>The number of test shards to use per browser. (default: 1)</p> + </td> + </tr> + <tr id="ts_web_test_suite.size"> + <td><code>size</code></td> + <td> + <p><code>Unknown; Optional</code></p> + <p>A string specifying the test size. (default: 'large')</p> + </td> + </tr> + <tr id="ts_web_test_suite.tags"> + <td><code>tags</code></td> + <td> + <p><code>List of strings; Optional</code></p> + <p>A list of test tag strings to apply to each generated web_test_suite target. +This macro adds a couple for ibazel.</p> + </td> + </tr> + <tr id="ts_web_test_suite.test_suite_tags"> + <td><code>test_suite_tags</code></td> + <td> + <p><code>Unknown; Optional</code></p> + <p>A list of tag strings for the generated test_suite.</p> + </td> + </tr> + <tr id="ts_web_test_suite.timeout"> + <td><code>timeout</code></td> + <td> + <p><code>Unknown; Optional</code></p> + <p>A string specifying the test timeout (default: computed from size)</p> + </td> + </tr> + <tr id="ts_web_test_suite.visibility"> + <td><code>visibility</code></td> + <td> + <p><code>Unknown; Optional</code></p> + <p>List of labels; optional.</p> + </td> + </tr> + <tr id="ts_web_test_suite.web_test_data"> + <td><code>web_test_data</code></td> + <td> + <p><code>List of strings; Optional</code></p> + <p>Data dependencies for the web_test_suite.</p> + </td> + </tr> + <tr id="ts_web_test_suite.wrapped_test_tags"> + <td><code>wrapped_test_tags</code></td> + <td> + <p><code>Unknown; Optional</code></p> + <p>A list of test tag strings to use for the wrapped test</p> + </td> + </tr> + <tr id="ts_web_test_suite.**remaining_keyword_args"> + <td><code>**remaining_keyword_args</code></td> + <td> + <p><code>Unknown; Optional</code></p> + <p>Arguments for the wrapped test target.</p> + </td> + </tr> + </tbody> +</table>
diff --git a/internal/karma/package.json b/internal/karma/package.json index 5f71978..e714d26 100644 --- a/internal/karma/package.json +++ b/internal/karma/package.json
@@ -43,5 +43,8 @@ "compatVersion": "0.0.0-COMPAT_VERSION", "rootPath": "." } + }, + "scripts": { + "skydoc": "bazel build --symlink_prefix=bazel- //docs && unzip -o -d docs bazel-bin/docs/docs-skydoc.zip && cat docs/install.md docs/*_web_test.md | sed 's/^##/\\\n##/' > README.md" } }