Google Git
Sign in
pigweed/third_party/github/bazel-contrib/rules_nodejs/4709ffbb064697b337dfd6f1d98cbdca4e939559/./docs/Concatjs.html
blob: bb5901d7de8228a58b141cb8275ae3826bf91a69 [file] [log] [blame]
<!DOCTYPE html>
<html itemscope itemtype="https://schema.org/WebPage" lang="en">
<head>
<meta charset="utf-8">
<meta content="IE=edge" http-equiv="X-UA-Compatible">
<meta content="width=device-width, initial-scale=1" name="viewport">
<link href="/rules_nodejs/Concatjs.html" rel="canonical">
<link href="" rel="shortcut icon" type="image/png">
<title>rules_nodejs - Concatjs</title>
<!-- Webfont -->
<link href="//fonts.googleapis.com/css?family=Source+Code+Pro:400,500,700|Open+Sans:400,600,700,800" rel="stylesheet">
<!-- Bootstrap -->
<link crossorigin="anonymous" href="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.7/css/bootstrap.min.css"
integrity="sha384-BVYiiSIFeK1dGmJRAkycuHAHRg32OmUcww7on3RYdg4Va+PmSTsz/K68vbdEjh4u" rel="stylesheet">
<!-- Font Awesome -->
<link href="https://stackpath.bootstrapcdn.com/font-awesome/4.7.0/css/font-awesome.min.css" rel="stylesheet">
<!-- HTML5 shim and Respond.js for IE8 support of HTML5 elements and media queries -->
<!-- WARNING: Respond.js doesn't work if you view the page via file:// -->
<!--[if lt IE 9]>
<script src="https://oss.maxcdn.com/html5shiv/3.7.2/html5shiv.min.js"></script>
<script src="https://oss.maxcdn.com/respond/1.4.2/respond.min.js"></script>
<![endif]-->
<!-- Custom stylesheet -->
<link href="/rules_nodejs/css/main.css" rel="stylesheet">
<!-- metadata -->
<meta content="rules_nodejs" name="og:title"/>
<meta content="JavaScript and NodeJS rules for Bazel" name="og:description"/>
</head>
<body>
<nav class="navbar navbar-inverse navbar-fixed-top" id="common-nav">
<div class="container">
<!-- Brand and toggle get grouped for better mobile display -->
<div class="navbar-header">
<button class="navbar-toggle collapsed" data-target="#bs-example-navbar-collapse-1" data-toggle="collapse"
type="button">
<span class="sr-only">Toggle navigation</span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
</button>
<a class="navbar-brand" href="/rules_nodejs/">
<img class="navbar-logo" src="/rules_nodejs/images/bazel-navbar.svg">
</a>
</div>
<!-- Collect the nav links, forms, and other content for toggling -->
<div class="collapse navbar-collapse" id="bs-example-navbar-collapse-1">
<form class="navbar-form navbar-right" action="/rules_nodejs/search.html" id="cse-search-box">
<div class="form-group">
<input type="hidden" name="cx" value="2735dc72dd157bd19">
<input type="search" name="q" id="q" class="form-control input-sm" placeholder="Search">
</div>
</form>
<ul class="nav navbar-nav navbar-right">
<li><a href="https://github.com/bazelbuild/rules_nodejs">GitHub</a></li>
</ul>
</div><!-- /.navbar-collapse -->
</div><!-- /.container-fluid -->
</nav>
<div class="container vpad">
<div class="row">
<div class="col-md-2">
<a aria-controls="sidebar-nav"
aria-expanded="false" class="btn btn-default btn-lg btn-block sidebar-toggle" data-toggle="collapse"
href="#sidebar-nav">
<i class="glyphicon glyphicon-menu-hamburger"></i> Navigation
</a>
<nav class="sidebar collapse" id="sidebar-nav">
<select onchange="location.href=this.value">
<option selected disabled hidden>Version: 3.x</option>
<option value="/rules_nodejs/Concatjs.html">3.x</option>
<option value="https://docs.aspect.dev/rules_nodejs/Concatjs.html">2.3</option>
</select>
<h3>rules_nodejs</h3>
<ul class="sidebar-nav">
<li><a href="/rules_nodejs/">Introduction</a></li>
<li><a href="install.html">Installation</a></li>
<li><a href="repositories.html">Repositories</a></li>
<li><a href="dependencies.html">Dependencies</a></li>
<li><a href="debugging.html">Debugging</a></li>
<li><a href="stamping.html">Stamping</a></li>
<li><a href="changing-rules.html">Making changes to rules_nodejs</a></li>
<li><a href="examples.html">Examples</a></li>
</ul>
<h3>Rules</h3>
<ul class="sidebar-nav">
<li><a href="/rules_nodejs/Built-ins.html">Built-ins</a></li>
<li><a href="/rules_nodejs/Concatjs.html">Concatjs</a></li>
<li><a href="/rules_nodejs/Cypress.html">Cypress</a></li>
<li><a href="/rules_nodejs/Jasmine.html">Jasmine</a></li>
<li><a href="/rules_nodejs/Labs.html">Labs</a></li>
<li><a href="/rules_nodejs/Protractor.html">Protractor</a></li>
<li><a href="/rules_nodejs/Providers.html">Providers</a></li>
<li><a href="/rules_nodejs/Rollup.html">Rollup</a></li>
<li><a href="/rules_nodejs/Terser.html">Terser</a></li>
<li><a href="/rules_nodejs/TypeScript.html">TypeScript</a></li>
<li><a href="/rules_nodejs/esbuild.html">esbuild</a></li>
</ul>
<h3>Community</h3>
<ul class="sidebar-nav">
<li><a href="https://github.com/bazelbuild/rules_nodejs/blob/master/CONTRIBUTING.md">Contribute to
rules_nodejs</a></li>
<li><a href="https://slack.bazel.build">Join #javascript on Slack</a></li>
<li><a href="https://github.com/bazelbuild/rules_nodejs/issues">Issue Tracker</a></li>
<li><a href="https://github.com/bazelbuild/rules_nodejs">Github</a></li>
</ul>
</nav>
</div>
<div class="col-md-8">
<div class="content">
<!-- *********************
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
********************* -->
<h1 id="bazelconcatjs">@bazel/concatjs</h1>
<p>Concatjs is a JavaScript bundler, in a trivial sense: the UNIX <code class="language-plaintext highlighter-rouge">cat</code> command is a basic implementation:</p>
<div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nv">$ </span><span class="nb">cat </span>one.js two.js <span class="o">&gt;</span> bundle.js
</code></pre></div></div>
<p>Clearly self-evident is that this bundler is super-fast and simple.
A performant implementation adds some in-memory caching, and for developer ergonomics you add a simple IIFE wrapper
around each file so that the Chrome DevTools shows the files in the tree as if they had been independently loaded.</p>
<p>However at its core, concatjs requires a big tradeoff of a migration cost to buy-in, to get this incredible performance.
The path of the JavaScript files is lost in the bundling process, so they must contain their module ID internally.</p>
<p><a href="https://requirejs.org/docs/whyamd.html#namedmodules">Named AMD/UMD modules</a> and <code class="language-plaintext highlighter-rouge">goog.module</code> are the two JS module formats that are compatible with concatjs.
Most packages do not ship with this format, so in order to use concatjs tooling, you have to shim your code and dependencies. See the <a href="#compatibility">Compatibility</a> section below.</p>
<p>This is at the core of how Google does JavaScript development.
So Bazel rules that originated in Google’s codebase have affordances for concatjs.
For example <code class="language-plaintext highlighter-rouge">ts_library</code> produces named AMD modules in its “devmode” output, and
<code class="language-plaintext highlighter-rouge">karma_web_test</code> expects to bundle inputs using concatjs.</p>
<h2 id="compatibility">Compatibility</h2>
<h3 id="first-party-code">First-party code</h3>
<p>First-party code has to be authored as named AMD/UMD modules.
This is also historically referred to as “RequireJS” modules since that’s the
JS loader that is typically used with them.</p>
<p>If you write TypeScript, you can do this following their <a href="https://www.typescriptlang.org/docs/handbook/modules.html">documentation</a>.</p>
<p>There is an example in this repository: we have an <code class="language-plaintext highlighter-rouge">index.ts</code> file that wants
to be used with require.js <code class="language-plaintext highlighter-rouge">require("@bazel/concatjs")</code>.
So it
<a href="https://github.com/bazelbuild/rules_nodejs/blob/bd53eb524ea3bd56b46b7a5f2eff700443e281ec/packages/concatjs/index.ts#L1">declares
that module name</a>
using the TS triple-slash syntax:</p>
<div class="language-typescript highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c1">///&lt;amd-module name="@bazel/concatjs"/&gt;</span>
</code></pre></div></div>
<p>it is <a href="https://github.com/bazelbuild/rules_nodejs/blob/bd53eb524ea3bd56b46b7a5f2eff700443e281ec/packages/concatjs/BUILD.bazel#L28">also compiled with</a>
the <code class="language-plaintext highlighter-rouge">"compilerOptions": { "module": "umd" }</code> TypeScript setting.</p>
<h3 id="third-party-code">Third-party code</h3>
<p>To make it easier to produce a UMD version of a third-party npm package, we automatically generate a target that uses Browserify to build one, using the <code class="language-plaintext highlighter-rouge">main</code> entry from the package’s <code class="language-plaintext highlighter-rouge">package.json</code>.
In most cases this will make the package loadable under concatjs.
This target has a <code class="language-plaintext highlighter-rouge">__umd</code> suffix. For example, if your library is at <code class="language-plaintext highlighter-rouge">@npm//foo</code> then the UMD target is <code class="language-plaintext highlighter-rouge">@npm//foo:foo__umd</code>.</p>
<p>An example where this fixes a users issue: <a href="https://github.com/bazelbuild/rules_nodejs/issues/2317#issuecomment-735921318">https://github.com/bazelbuild/rules_nodejs/issues/2317#issuecomment-735921318</a></p>
<p>In some cases, the generated UMD bundle is not sufficient, and in others it fails to build because it requires some special Browserify configuration.
You can always write your own shim that grabs a symbol from a package you use, and exposes it in an AMD/require.js-compatible way.
For example, even though RxJS ships with a UMD bundle, it contains multiple entry points and uses anonymous modules, not named modules. So our Angular/concatjs example has a <code class="language-plaintext highlighter-rouge">rxjs_shims.js</code> file that exposes some RxJS operators, then at <a href="https://github.com/bazelbuild/rules_nodejs/blob/2.3.1/examples/angular/src/BUILD.bazel#L65-L71">https://github.com/bazelbuild/rules_nodejs/blob/2.3.1/examples/angular/src/BUILD.bazel#L65-L71</a> this is combined in a <code class="language-plaintext highlighter-rouge">filegroup</code> with the <code class="language-plaintext highlighter-rouge">rxjs.umd.js</code> file. Now we use this filegroup target when depending on RxJS in a <code class="language-plaintext highlighter-rouge">concatjs_*</code> rule.</p>
<p>Ultimately by using concatjs, you’re signing up for at least a superficial understanding of these shims and may need to update them when you change your dependencies.</p>
<h2 id="serving-js-in-development-mode-under-bazel">Serving JS in development mode under Bazel</h2>
<p>There are two choices for development mode:</p>
<ol>
<li>Use the <code class="language-plaintext highlighter-rouge">concatjs_devserver</code> rule to bring up our simple, fast development server.
This is intentionally very simple, to help you get started quickly. However,
since there are many development servers available, we do not want to mirror
their features in yet another server we maintain.</li>
<li>Teach your real frontend server to serve files from Bazel’s output directory.
This is not yet documented. Choose this option if you have an existing server
used in development mode, or if your requirements exceed what the
<code class="language-plaintext highlighter-rouge">concatjs_devserver</code> supports. Be careful that your development round-trip stays
fast (should be under two seconds).</li>
</ol>
<p>To use <code class="language-plaintext highlighter-rouge">concatjs_devserver</code>, you simply <code class="language-plaintext highlighter-rouge">load</code> the rule, and call it with <code class="language-plaintext highlighter-rouge">deps</code> that
point to your <code class="language-plaintext highlighter-rouge">ts_library</code> target(s):</p>
<div class="language-python highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="n">load</span><span class="p">(</span><span class="s">"@npm//@bazel/concatjs:index.bzl"</span><span class="p">,</span> <span class="s">"concatjs_devserver"</span><span class="p">)</span>
<span class="n">load</span><span class="p">(</span><span class="s">"@npm//@bazel/typescript:index.bzl"</span><span class="p">,</span> <span class="s">"ts_library"</span><span class="p">)</span>
<span class="n">ts_library</span><span class="p">(</span>
<span class="n">name</span> <span class="o">=</span> <span class="s">"app"</span><span class="p">,</span>
<span class="n">srcs</span> <span class="o">=</span> <span class="p">[</span><span class="s">"app.ts"</span><span class="p">],</span>
<span class="p">)</span>
<span class="n">concatjs_devserver</span><span class="p">(</span>
<span class="n">name</span> <span class="o">=</span> <span class="s">"devserver"</span><span class="p">,</span>
<span class="c1"># We'll collect all the devmode JS sources from these TypeScript libraries
</span> <span class="n">deps</span> <span class="o">=</span> <span class="p">[</span><span class="s">":app"</span><span class="p">],</span>
<span class="c1"># This is the path we'll request from the browser, see index.html
</span> <span class="n">serving_path</span> <span class="o">=</span> <span class="s">"/bundle.js"</span><span class="p">,</span>
<span class="c1"># The devserver can serve our static files too
</span> <span class="n">static_files</span> <span class="o">=</span> <span class="p">[</span><span class="s">"index.html"</span><span class="p">],</span>
<span class="p">)</span>
</code></pre></div></div>
<p>The <code class="language-plaintext highlighter-rouge">index.html</code> should be the same one you use for production, and it should
load the JavaScript bundle from the path indicated in <code class="language-plaintext highlighter-rouge">serving_path</code>.</p>
<p>If you don’t have an index.html file, a simple one will be generated by the
<code class="language-plaintext highlighter-rouge">concatjs_devserver</code>.</p>
<p>See <code class="language-plaintext highlighter-rouge">examples/app</code> in this repository for a working example. To run the
devserver, we recommend you use <a href="https://github.com/bazelbuild/bazel-watcher">ibazel</a>:</p>
<div class="language-sh highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nv">$ </span>ibazel run examples/app:devserver
</code></pre></div></div>
<p><code class="language-plaintext highlighter-rouge">ibazel</code> will keep the devserver program running, and provides a LiveReload
server so the browser refreshes the application automatically when each build
finishes.</p>
<h2 id="testing-with-karma">Testing with Karma</h2>
<p>The <code class="language-plaintext highlighter-rouge">karma_web_test</code> rule runs karma tests with Bazel.</p>
<p>It depends on rules_webtesting, so you need to add this to your <code class="language-plaintext highlighter-rouge">WORKSPACE</code>
if you use the web testing rules in <code class="language-plaintext highlighter-rouge">@bazel/concatjs</code>:</p>
<div class="language-python highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c1"># Fetch transitive Bazel dependencies of karma_web_test
</span><span class="n">http_archive</span><span class="p">(</span>
<span class="n">name</span> <span class="o">=</span> <span class="s">"io_bazel_rules_webtesting"</span><span class="p">,</span>
<span class="n">sha256</span> <span class="o">=</span> <span class="s">"9bb461d5ef08e850025480bab185fd269242d4e533bca75bfb748001ceb343c3"</span><span class="p">,</span>
<span class="n">urls</span> <span class="o">=</span> <span class="p">[</span><span class="s">"https://github.com/bazelbuild/rules_webtesting/releases/download/0.3.3/rules_webtesting.tar.gz"</span><span class="p">],</span>
<span class="p">)</span>
<span class="c1"># Set up web testing, choose browsers we can test on
</span><span class="n">load</span><span class="p">(</span><span class="s">"@io_bazel_rules_webtesting//web:repositories.bzl"</span><span class="p">,</span> <span class="s">"web_test_repositories"</span><span class="p">)</span>
<span class="n">web_test_repositories</span><span class="p">()</span>
<span class="n">load</span><span class="p">(</span><span class="s">"@io_bazel_rules_webtesting//web/versioned:browsers-0.3.2.bzl"</span><span class="p">,</span> <span class="s">"browser_repositories"</span><span class="p">)</span>
<span class="n">browser_repositories</span><span class="p">(</span>
<span class="n">chromium</span> <span class="o">=</span> <span class="bp">True</span><span class="p">,</span>
<span class="n">firefox</span> <span class="o">=</span> <span class="bp">True</span><span class="p">,</span>
<span class="p">)</span>
</code></pre></div></div>
<h2 id="installing-with-user-managed-dependencies">Installing with user-managed dependencies</h2>
<p>If you didn’t use the <code class="language-plaintext highlighter-rouge">yarn_install</code> or <code class="language-plaintext highlighter-rouge">npm_install</code> rule to create an <code class="language-plaintext highlighter-rouge">npm</code> workspace, you’ll have to declare a rule in your root <code class="language-plaintext highlighter-rouge">BUILD.bazel</code> file to execute karma:</p>
<div class="language-python highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c1"># Create a karma rule to use in karma_web_test_suite karma
# attribute when using user-managed dependencies
</span><span class="n">nodejs_binary</span><span class="p">(</span>
<span class="n">name</span> <span class="o">=</span> <span class="s">"karma/karma"</span><span class="p">,</span>
<span class="n">entry_point</span> <span class="o">=</span> <span class="s">"//:node_modules/karma/bin/karma"</span><span class="p">,</span>
<span class="c1"># Point bazel to your node_modules to find the entry point
</span> <span class="n">data</span> <span class="o">=</span> <span class="p">[</span><span class="s">"//:node_modules"</span><span class="p">],</span>
<span class="p">)</span>
</code></pre></div></div>
<h2 id="concatjs_devserver">concatjs_devserver</h2>
<p><strong>USAGE</strong></p>
<pre>
concatjs_devserver(<a href="#concatjs_devserver-name">name</a>, <a href="#concatjs_devserver-additional_root_paths">additional_root_paths</a>, <a href="#concatjs_devserver-bootstrap">bootstrap</a>, <a href="#concatjs_devserver-deps">deps</a>, <a href="#concatjs_devserver-devserver">devserver</a>, <a href="#concatjs_devserver-devserver_host">devserver_host</a>,
<a href="#concatjs_devserver-entry_module">entry_module</a>, <a href="#concatjs_devserver-port">port</a>, <a href="#concatjs_devserver-scripts">scripts</a>, <a href="#concatjs_devserver-serving_path">serving_path</a>, <a href="#concatjs_devserver-static_files">static_files</a>)
</pre>
<p>concatjs_devserver is a simple development server intended for a quick “getting started” experience.</p>
<p>Additional documentation <a href="https://github.com/alexeagle/angular-bazel-example/wiki/Running-a-devserver-under-Bazel">here</a></p>
<p><strong>ATTRIBUTES</strong></p>
<h4 id="concatjs_devserver-name">name</h4>
<p>(<em><a href="https://bazel.build/docs/build-ref.html#name">Name</a>, mandatory</em>): A unique name for this target.</p>
<h4 id="concatjs_devserver-additional_root_paths">additional_root_paths</h4>
<p>(<em>List of strings</em>): Additional root paths to serve <code class="language-plaintext highlighter-rouge">static_files</code> from.
Paths should include the workspace name such as <code class="language-plaintext highlighter-rouge">["__main__/resources"]</code></p>
<p>Defaults to <code class="language-plaintext highlighter-rouge">[]</code></p>
<h4 id="concatjs_devserver-bootstrap">bootstrap</h4>
<p>(<em><a href="https://bazel.build/docs/build-ref.html#labels">List of labels</a></em>): Scripts to include in the JS bundle before the module loader (require.js)</p>
<p>Defaults to <code class="language-plaintext highlighter-rouge">[]</code></p>
<h4 id="concatjs_devserver-deps">deps</h4>
<p>(<em><a href="https://bazel.build/docs/build-ref.html#labels">List of labels</a></em>): Targets that produce JavaScript, such as <code class="language-plaintext highlighter-rouge">ts_library</code></p>
<p>Defaults to <code class="language-plaintext highlighter-rouge">[]</code></p>
<h4 id="concatjs_devserver-devserver">devserver</h4>
<p>(<em><a href="https://bazel.build/docs/build-ref.html#labels">Label</a></em>): Go based devserver executable.</p>
<div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code> With cross-platform RBE for OSX &amp; Windows ctx.executable.devserver will be linux as --cpu and
--host_cpu must be overridden to k8. However, we still want to be able to run the devserver on the host
machine so we need to include the host devserver binary, which is ctx.executable.devserver_host, in the
runfiles. For non-RBE and for RBE with a linux host, ctx.executable.devserver &amp; ctx.executable.devserver_host
will be the same binary.
Defaults to precompiled go binary setup by @bazel/typescript npm package
</code></pre></div></div>
<p>Defaults to <code class="language-plaintext highlighter-rouge">@npm//@bazel/concatjs/devserver:devserver</code></p>
<h4 id="concatjs_devserver-devserver_host">devserver_host</h4>
<p>(<em><a href="https://bazel.build/docs/build-ref.html#labels">Label</a></em>): Go based devserver executable for the host platform.
Defaults to precompiled go binary setup by @bazel/typescript npm package</p>
<p>Defaults to <code class="language-plaintext highlighter-rouge">@npm//@bazel/concatjs/devserver:devserver_darwin_amd64</code></p>
<h4 id="concatjs_devserver-entry_module">entry_module</h4>
<p>(<em>String</em>): The <code class="language-plaintext highlighter-rouge">entry_module</code> should be the AMD module name of the entry module such as <code class="language-plaintext highlighter-rouge">"__main__/src/index".</code>
<code class="language-plaintext highlighter-rouge">concatjs_devserver</code> concats the following snippet after the bundle to load the application:
<code class="language-plaintext highlighter-rouge">require(["entry_module"]);</code></p>
<p>Defaults to <code class="language-plaintext highlighter-rouge">""</code></p>
<h4 id="concatjs_devserver-port">port</h4>
<p>(<em>Integer</em>): The port that the devserver will listen on.</p>
<p>Defaults to <code class="language-plaintext highlighter-rouge">5432</code></p>
<h4 id="concatjs_devserver-scripts">scripts</h4>
<p>(<em><a href="https://bazel.build/docs/build-ref.html#labels">List of labels</a></em>): User scripts to include in the JS bundle before the application sources</p>
<p>Defaults to <code class="language-plaintext highlighter-rouge">[]</code></p>
<h4 id="concatjs_devserver-serving_path">serving_path</h4>
<p>(<em>String</em>): The path you can request from the client HTML which serves the JavaScript bundle.
If you don’t specify one, the JavaScript can be loaded at /_/ts_scripts.js</p>
<p>Defaults to <code class="language-plaintext highlighter-rouge">"/_/ts_scripts.js"</code></p>
<h4 id="concatjs_devserver-static_files">static_files</h4>
<p>(<em><a href="https://bazel.build/docs/build-ref.html#labels">List of labels</a></em>): Arbitrary files which to be served, such as index.html.
They are served relative to the package where this rule is declared.</p>
<p>Defaults to <code class="language-plaintext highlighter-rouge">[]</code></p>
<h2 id="karma_web_test">karma_web_test</h2>
<p><strong>USAGE</strong></p>
<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-peer_deps">peer_deps</a>, <a href="#karma_web_test-kwargs">kwargs</a>)
</pre>
<p>Runs unit tests in a browser with Karma.</p>
<p>When executed under <code class="language-plaintext highlighter-rouge">bazel test</code>, this uses a headless browser for speed.
This is also because <code class="language-plaintext highlighter-rouge">bazel test</code> 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 <code class="language-plaintext highlighter-rouge">bazel test</code> the test will execute and immediately terminate.</p>
<p>Running under <code class="language-plaintext highlighter-rouge">ibazel test</code> 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.</p>
<p>To debug a single test target, run it with <code class="language-plaintext highlighter-rouge">bazel run</code> 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 <code class="language-plaintext highlighter-rouge">bazel run</code> command.</p>
<p>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 <code class="language-plaintext highlighter-rouge">browsers</code> and <code class="language-plaintext highlighter-rouge">customLaunchers</code> may be set using the a base Karma configuration
specified in the <code class="language-plaintext highlighter-rouge">config_file</code> attribute.</p>
<p>By default we open a headless Chrome. To use a real Chrome browser window, you can pass
<code class="language-plaintext highlighter-rouge">--define DISPLAY=true</code> to Bazel, along with <code class="language-plaintext highlighter-rouge">configuration_env_vars = ["DISPLAY"]</code> on
<code class="language-plaintext highlighter-rouge">karma_web_test</code>.</p>
<p><strong>PARAMETERS</strong></p>
<h4 id="karma_web_test-srcs">srcs</h4>
<p>A list of JavaScript test files</p>
<p>Defaults to <code class="language-plaintext highlighter-rouge">[]</code></p>
<h4 id="karma_web_test-deps">deps</h4>
<p>Other targets which produce JavaScript such as <code class="language-plaintext highlighter-rouge">ts_library</code></p>
<p>Defaults to <code class="language-plaintext highlighter-rouge">[]</code></p>
<h4 id="karma_web_test-data">data</h4>
<p>Runtime dependencies</p>
<p>Defaults to <code class="language-plaintext highlighter-rouge">[]</code></p>
<h4 id="karma_web_test-configuration_env_vars">configuration_env_vars</h4>
<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>
<p>Defaults to <code class="language-plaintext highlighter-rouge">[]</code></p>
<h4 id="karma_web_test-bootstrap">bootstrap</h4>
<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>
<p>Defaults to <code class="language-plaintext highlighter-rouge">[]</code></p>
<h4 id="karma_web_test-runtime_deps">runtime_deps</h4>
<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 class="language-plaintext highlighter-rouge">ts_library</code>.
The files will be loaded in the same order they are declared by that rule.</p>
<p>Defaults to <code class="language-plaintext highlighter-rouge">[]</code></p>
<h4 id="karma_web_test-static_files">static_files</h4>
<p>Arbitrary files which are available to be served on request.
Files are served at:
<code class="language-plaintext highlighter-rouge">/base/&amp;lt;WORKSPACE_NAME&amp;gt;/&amp;lt;path-to-file&amp;gt;</code>, e.g.
<code class="language-plaintext highlighter-rouge">/base/npm_bazel_typescript/examples/testing/static_script.js</code></p>
<p>Defaults to <code class="language-plaintext highlighter-rouge">[]</code></p>
<h4 id="karma_web_test-config_file">config_file</h4>
<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>
<p>Defaults to <code class="language-plaintext highlighter-rouge">None</code></p>
<h4 id="karma_web_test-tags">tags</h4>
<p>Standard Bazel tags, this macro adds tags for ibazel support</p>
<p>Defaults to <code class="language-plaintext highlighter-rouge">[]</code></p>
<h4 id="karma_web_test-peer_deps">peer_deps</h4>
<p>list of peer npm deps required by karma_web_test</p>
<p>Defaults to <code class="language-plaintext highlighter-rouge">["@npm//karma", "@npm//karma-chrome-launcher", "@npm//karma-firefox-launcher", "@npm//karma-jasmine", "@npm//karma-requirejs", "@npm//karma-sourcemap-loader", "@npm//requirejs"]</code></p>
<h4 id="karma_web_test-kwargs">kwargs</h4>
<p>Passed through to <code class="language-plaintext highlighter-rouge">karma_web_test</code></p>
<h2 id="karma_web_test_suite">karma_web_test_suite</h2>
<p><strong>USAGE</strong></p>
<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-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-kwargs">kwargs</a>)
</pre>
<p>Defines a test_suite of web_test targets that wrap a karma_web_test target.</p>
<p>This macro accepts all parameters in karma_web_test and adds additional parameters
for the suite. See karma_web_test docs for all karma_web_test.</p>
<p>The wrapping macro is <code class="language-plaintext highlighter-rouge">web_test_suite</code> which comes from rules_websting:
https://github.com/bazelbuild/rules_webtesting/blob/master/web/web.bzl.</p>
<p><strong>PARAMETERS</strong></p>
<h4 id="karma_web_test_suite-name">name</h4>
<p>The base name of the test</p>
<h4 id="karma_web_test_suite-browsers">browsers</h4>
<p>A sequence of labels specifying the browsers to use.</p>
<p>Defaults to <code class="language-plaintext highlighter-rouge">None</code></p>
<h4 id="karma_web_test_suite-web_test_data">web_test_data</h4>
<p>Data dependencies for the wrapper web_test targets.</p>
<p>Defaults to <code class="language-plaintext highlighter-rouge">[]</code></p>
<h4 id="karma_web_test_suite-wrapped_test_tags">wrapped_test_tags</h4>
<p>A list of test tag strings to use for the wrapped
karma_web_test target.</p>
<p>Defaults to <code class="language-plaintext highlighter-rouge">["manual", "noci"]</code></p>
<h4 id="karma_web_test_suite-kwargs">kwargs</h4>
<p>Arguments for the wrapped karma_web_test target.</p>
</div>
</div>
<div class="col-md-2 sticky-sidebar">
<div class="right-sidebar">
<ul class="gh-links">
<li>
<i class="fa fa-github"></i>
<a href="https://github.com/bazelbuild/rules_nodejs/issues/new?title=Documentation issue: Concatjs&labels=question/docs">Create
issue</a>
</li>
</ul>
<ul class="section-nav">
<li class="toc-entry toc-h2"><a href="#compatibility">Compatibility</a>
<ul>
<li class="toc-entry toc-h3"><a href="#first-party-code">First-party code</a></li>
<li class="toc-entry toc-h3"><a href="#third-party-code">Third-party code</a></li>
</ul>
</li>
<li class="toc-entry toc-h2"><a href="#serving-js-in-development-mode-under-bazel">Serving JS in development mode under Bazel</a></li>
<li class="toc-entry toc-h2"><a href="#testing-with-karma">Testing with Karma</a></li>
<li class="toc-entry toc-h2"><a href="#installing-with-user-managed-dependencies">Installing with user-managed dependencies</a></li>
<li class="toc-entry toc-h2"><a href="#concatjs_devserver">concatjs_devserver</a></li>
<li class="toc-entry toc-h2"><a href="#karma_web_test">karma_web_test</a></li>
<li class="toc-entry toc-h2"><a href="#karma_web_test_suite">karma_web_test_suite</a></li>
</ul>
</div>
</div>
</div>
</div>
<footer class="footer">
<div class="container">
<div class="row">
<div class="col-lg-8">
<p class="text-muted">&copy; 2021 The rules_nodejs authors</p>
</div>
</div>
</div>
</footer>
<!-- jQuery (necessary for Bootstrap's JavaScript plugins) -->
<script src="https://ajax.googleapis.com/ajax/libs/jquery/1.11.2/jquery.min.js"></script>
<!-- Include all compiled plugins (below), or include individual files as needed -->
<script crossorigin="anonymous"
integrity="sha384-Tc5IQib027qvyjSMfHjOMaLkfuWVxZxUPnCJA7l2mCWNIpG9mGCD8wGNIcPD7Txa"
src="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.7/js/bootstrap.min.js"></script>
<!-- Anchor JS -->
<script src="https://cdnjs.cloudflare.com/ajax/libs/anchor-js/3.2.0/anchor.min.js" type="text/javascript"></script>
<script>
// Automatically add anchors and links to all header elements that don't already have them.
anchors.options = { placement: 'left' };
anchors.add();
</script>
<script>
var shiftWindow = function () {
if (location.hash.length !== 0) {
window.scrollBy(0, -50);
}
};
window.addEventListener("hashchange", shiftWindow);
var highlightCurrentSidebarNav = function () {
var href = location.pathname;
var item = $('#sidebar-nav [href$="' + href + '"]');
if (item) {
var li = item.parent();
li.addClass("active");
if (li.parent() && li.parent().is("ul")) {
do {
var ul = li.parent();
if (ul.hasClass("collapse")) {
ul.collapse("show");
}
li = ul.parent();
} while (li && li.is("li"));
}
}
};
$(document).ready(function () {
// Scroll to anchor of location hash, adjusted for fixed navbar.
window.setTimeout(function () {
shiftWindow();
}, 1);
// Flip the caret when submenu toggles are clicked.
$(".sidebar-submenu").on("show.bs.collapse", function () {
var toggle = $('[href$="#' + $(this).attr('id') + '"]');
if (toggle) {
toggle.addClass("dropup");
}
});
$(".sidebar-submenu").on("hide.bs.collapse", function () {
var toggle = $('[href$="#' + $(this).attr('id') + '"]');
if (toggle) {
toggle.removeClass("dropup");
}
});
// Highlight the current page on the sidebar nav.
highlightCurrentSidebarNav();
});
</script>
</body>
</html>