Debian Codegraph @

bazel/karma/karma_test.bzl

raw
1 """
2 THIS IS THE EXTERNAL-ONLY VERSION OF THIS FILE. G3 DOES NOT HAVE ONE AT ALL.
3
4 This module defines rules for running JS tests in a browser.
5
6 """
7
8 # https://github.com/google/skia-buildbot/blob/main/bazel/test_on_env/test_on_env.bzl
9 load("@org_skia_go_infra//bazel/test_on_env:test_on_env.bzl", "test_on_env")
10
11 # https://github.com/bazelbuild/rules_webtesting/blob/master/web/web.bzl
12 load("@rules_webtesting//web:web.bzl", "web_test")
13
14 def karma_test(name, config_file, srcs, static_files = None, env = None, **kwargs):
15 """Tests the given JS files using Karma and a browser provided by Bazel (Chromium)
16
17 This rule injects some JS code into the karma config file and produces both that modified
18 configuration file and a bash script which invokes Karma. That script is then invoked
19 in an environment that has the Bazel-downloaded browser available and the tests run using it.
20
21 When invoked via `bazel test`, the test runs in headless mode. When invoked via `bazel run`,
22 a visible web browser appears for the user to inspect and debug.
23
24 This draws inspiration from the karma_web_test implementation in concatjs
25 https://github.com/bazelbuild/rules_nodejs/blob/700b7a3c5f97f2877320e6e699892ee706f85269/packages/concatjs/web_test/karma_web_test.bzl
26 https://github.com/bazelbuild/rules_nodejs/blob/c0b5865d7926298206e9a6aa32138967403ad1f2/packages/concatjs/web_test/karma_web_test.bzl
27 but we were unable to use it because they prevented us from defining some proxies ourselves,
28 which we need in order to communicate our test gms (PNG files) to a server that runs alongside
29 the test. This implementation is simpler than concatjs's and does not try to work for all
30 situations nor bundle everything together.
31
32 Args:
33 name: The name of the rule which actually runs the tests. generated dependent rules will use
34 this name plus an applicable suffix.
35 config_file: A karma config file. The user is to expect a function called BAZEL_APPLY_SETTINGS
36 is defined and should call it with the configuration object before passing it to config.set.
37 srcs: A list of JavaScript test files or helpers.
38 static_files: Arbitrary files which are available to be loaded.
39 Files are served at:
40 - `/static/<WORKSPACE_NAME>/<path-to-file>` or
41 - `/static/<WORKSPACE_NAME>/<path-to-rule>/<file>`
42 Examples:
43 - `/static/skia/modules/canvaskit/tests/assets/color_wheel.gif`
44 - `/static/skia/modules/canvaskit/canvaskit_wasm/canvaskit.wasm`
45 env: An optional label to a binary. If set, the test will be wrapped in a test_on_env rule,
46 and this binary will be used as the "env" part of test_on_env. It will be started before
47 the tests run and be running in parallel to them. See the test_on_env.bzl in the
48 Skia Infra repo for more.
49 **kwargs: Additional arguments are passed to @rules_webtesting/web_test.
50 """
51 if len(srcs) == 0:
52 fail("Must pass at least one file into srcs or there will be no tests to run")
53 if not static_files:
54 static_files = []
55
56 karma_test_name = name + "_karma_test"
57 _karma_test(
58 name = karma_test_name,
59 srcs = srcs,
60 config_file = config_file,
61 static_files = static_files,
62 visibility = ["//visibility:private"],
63 tags = ["manual", "no-remote"],
64 )
65
66 # See the following link for the options.
67 # https://github.com/bazelbuild/rules_webtesting/blob/e9cf17123068b1123c68219edf9b274bf057b9cc/web/internal/web_test.bzl#L164
68 # TODO(kjlubick) consider using web_test_suite to test on Firefox as well.
69 if not env:
70 web_test(
71 name = name,
72 launcher = ":" + karma_test_name,
73 browser = "@rules_webtesting//browsers:chromium-local",
74 test = karma_test_name,
75 tags = [
76 # https://bazel.build/reference/be/common-definitions#common.tags
77 "no-remote",
78 # native is required to be set by web_test for reasons that are not
79 # abundantly clear.
80 "native",
81 ],
82 **kwargs
83 )
84 else:
85 web_test_name = name + "_web_test"
86 web_test(
87 name = web_test_name,
88 launcher = ":" + karma_test_name,
89 browser = "@rules_webtesting//browsers:chromium-local",
90 test = karma_test_name,
91 visibility = ["//visibility:private"],
92 tags = [
93 # https://bazel.build/reference/be/common-definitions#common.tags
94 "no-remote",
95 "manual",
96 # native is required to be set by web_test for reasons that are not
97 # abundantly clear.
98 "native",
99 ],
100 **kwargs
101 )
102 test_on_env(
103 name = name,
104 env = env,
105 test = ":" + web_test_name,
106 test_on_env_binary = "@org_skia_go_infra//bazel/test_on_env:test_on_env",
107 tags = ["no-remote"],
108 )
109
110 # This JS code is injected into the the provided karma configuration file. It contains
111 # Bazel-specific logic that could be re-used across different configuration files.
112 # Concretely, it sets up the browser configuration and whether we want to just run the tests
113 # and exit (e.g. the user ran `bazel test foo`) or if we want to have an interactive session
114 # (e.g. the user ran `bazel run foo`).
115 _apply_bazel_settings_js_code = """
116 (function(cfg) {
117 // This is is a JS function provided via environment variables to let us resolve files
118 // https://bazelbuild.github.io/rules_nodejs/Built-ins.html#nodejs_binary-templated_args
119 const runfiles = require(process.env['BAZEL_NODE_RUNFILES_HELPER']);
120
121 // Apply the paths to any files that are coming from other Bazel rules (e.g. compiled JS).
122 function addFilePaths(cfg) {
123 if (!cfg.files) {
124 cfg.files = [];
125 }
126 cfg.files = cfg.files.concat([_BAZEL_SRCS]);
127 cfg.basePath = "_BAZEL_BASE_PATH";
128
129 if (!cfg.proxies) {
130 cfg.proxies = {};
131 }
132 // The following is based off of the concatjs version
133 // https://github.com/bazelbuild/rules_nodejs/blob/700b7a3c5f97f2877320e6e699892ee706f85269/packages/concatjs/web_test/karma.conf.js#L276
134 const staticFiles = [_BAZEL_STATIC_FILES];
135 for (const file of staticFiles) {
136 // We need to find the actual path (symlinks can apparently cause issues on Windows).
137 const resolvedFile = runfiles.resolve(file);
138 cfg.files.push({pattern: resolvedFile, included: false});
139 // We want the file to be available on a path according to its location in the workspace
140 // (and not the path on disk), so we use a proxy to redirect.
141 // Prefixing the proxy path with '/absolute' allows karma to load files that are not
142 // underneath the basePath. This doesn't see to be an official API.
143 // https://github.com/karma-runner/karma/issues/2703
144 cfg.proxies['/static/' + file] = '/absolute' + resolvedFile;
145 }
146 }
147
148 // Returns true if invoked with bazel run, i.e. the user wants to see the results on a real
149 // browser.
150 function isBazelRun() {
151 // This env var seems to be a good indicator on Linux, at least.
152 return !!process.env['DISPLAY'];
153 }
154
155 // Configures the settings to run chrome.
156 function applyChromiumSettings(cfg, chromiumPath) {
157 if (isBazelRun()) {
158 cfg.browsers = ['Chrome'];
159 cfg.singleRun = false;
160 } else {
161 // Invoked via bazel test, so run the tests once in a headless browser and be done
162 // When running on the CI, we saw errors like "No usable sandbox! Update your kernel or ..
163 // --no-sandbox". concatjs's version https://github.com/bazelbuild/rules_nodejs/blob/700b7a3c5f97f2877320e6e699892ee706f85269/packages/concatjs/web_test/karma.conf.js#L69
164 // detects if sandboxing is supported, but to avoid that complexity, we just always disable
165 // the sandbox. https://docs.travis-ci.com/user/chrome#karma-chrome-launcher
166 cfg.browsers = ['ChromeHeadlessNoSandbox'];
167 cfg.customLaunchers = {
168 'ChromeHeadlessNoSandbox': {
169 'base': 'ChromeHeadless',
170 'flags': [
171 '--no-sandbox',
172 // may help tests be less flaky
173 // https://peter.sh/experiments/chromium-command-line-switches/#browser-test
174 '--browser-test',
175 ],
176 },
177 }
178 cfg.singleRun = true;
179 }
180
181 try {
182 // Setting the CHROME_BIN environment variable tells Karma which chrome to use.
183 // We want it to use the Chrome brought via Bazel.
184 process.env.CHROME_BIN = runfiles.resolve(chromiumPath);
185 } catch {
186 throw new Error(`Failed to resolve Chromium binary '${chromiumPath}' in runfiles`);
187 }
188 }
189
190 function applyBazelSettings(cfg) {
191 addFilePaths(cfg)
192
193 // This is a JSON file that contains this metadata, mixed in with some other data, e.g.
194 // the link to the correct executable for the given platform.
195 // https://github.com/bazelbuild/rules_webtesting/blob/e9cf17123068b1123c68219edf9b274bf057b9cc/browsers/chromium-local.json
196 const webTestMetadata = require(runfiles.resolve(process.env['WEB_TEST_METADATA']));
197
198 const webTestFiles = webTestMetadata['webTestFiles'][0];
199 const path = webTestFiles['namedFiles']['CHROMIUM'];
200 if (path) {
201 applyChromiumSettings(cfg, path);
202 } else {
203 throw new Error("not supported yet");
204 }
205 }
206
207 applyBazelSettings(cfg)
208
209 function addPlugins(cfg) {
210 // Without listing these plugins, they will not be loaded (kjlubick suspects
211 // this has to do with karma/npm not being able to find them "globally"
212 // via some automagic process).
213 cfg.plugins = [
214 'karma-jasmine',
215 'karma-chrome-launcher',
216 'karma-firefox-launcher',
217 ];
218 }
219
220 addPlugins(cfg)
221
222 // The user is expected to treat the BAZEL_APPLY_SETTINGS as a function name and pass in
223 // the configuration as a parameter. Thus, we need to end such that our IIFE will be followed
224 // by the parameter in parentheses and get passed in as cfg.
225 })"""
226
227 def _expand_templates_in_karma_config(ctx):
228 # Wrap the absolute paths of our files in quotes and make them comma separated so they
229 # can go in the Karma files list.
230 srcs = ['"{}"'.format(_absolute_path(ctx, f)) for f in ctx.files.srcs]
231 src_list = ", ".join(srcs)
232
233 # Set our base path to that which contains the karma configuration file.
234 # This requires going up a few directory segments. This allows our absolute paths to
235 # all be compatible with each other.
236 config_segments = len(ctx.outputs.configuration.short_path.split("/"))
237 base_path = "/".join([".."] * config_segments)
238
239 static_files = ['"{}"'.format(_absolute_path(ctx, f)) for f in ctx.files.static_files]
240 static_list = ", ".join(static_files)
241
242 # Replace the placeholders in the embedded JS with those files. We cannot use .format() because
243 # the curly braces from the JS code throw it off.
244 apply_bazel_settings = _apply_bazel_settings_js_code.replace("_BAZEL_SRCS", src_list)
245 apply_bazel_settings = apply_bazel_settings.replace("_BAZEL_BASE_PATH", base_path)
246 apply_bazel_settings = apply_bazel_settings.replace("_BAZEL_STATIC_FILES", static_list)
247
248 # Add in the JS fragment that applies the Bazel-specific settings to the provided config.
249 # https://docs.bazel.build/versions/main/skylark/lib/actions.html#expand_template
250 ctx.actions.expand_template(
251 output = ctx.outputs.configuration,
252 template = ctx.file.config_file,
253 substitutions = {
254 "BAZEL_APPLY_SETTINGS": apply_bazel_settings,
255 },
256 )
257
258 def _absolute_path(ctx, file):
259 # Referencing things in @npm yields a short_path that starts with ../
260 # For those cases, we can just remove the ../
261 if file.short_path.startswith("../"):
262 return file.short_path[3:]
263
264 # Otherwise, we have a local file, so we need to include the workspace path to make it
265 # an absolute path
266 return ctx.workspace_name + "/" + file.short_path
267
268 _invoke_karma_bash_script = """#!/usr/bin/env bash
269 # --- begin runfiles.bash initialization v2 ---
270 # Copy-pasted from the Bazel Bash runfiles library v2.
271 # https://github.com/bazelbuild/bazel/blob/master/tools/bash/runfiles/runfiles.bash
272 set -uo pipefail; f=build_bazel_rules_nodejs/third_party/github.com/bazelbuild/bazel/tools/bash/runfiles/runfiles.bash
273 source "${{RUNFILES_DIR:-/dev/null}}/$f" 2>/dev/null || \
274 source "$(grep -sm1 "^$f " "${{RUNFILES_MANIFEST_FILE:-/dev/null}}" | cut -f2- -d' ')" 2>/dev/null || \
275 source "$0.runfiles/$f" 2>/dev/null || \
276 source "$(grep -sm1 "^$f " "$0.runfiles_manifest" | cut -f2- -d' ')" 2>/dev/null || \
277 source "$(grep -sm1 "^$f " "$0.exe.runfiles_manifest" | cut -f2- -d' ')" 2>/dev/null || \
278 {{ echo>&2 "ERROR: cannot find $f"; exit 1; }}; f=; set -e
279 # --- end runfiles.bash initialization v2 ---
280
281 readonly KARMA=$(rlocation "{_KARMA_EXECUTABLE_SCRIPT}")
282 readonly CONF=$(rlocation "{_KARMA_CONFIGURATION_FILE}")
283
284 # set a temporary directory as the home directory, because otherwise Chrome fails to
285 # start up, complaining about a read-only file system. This does not get cleaned up automatically
286 # by Bazel, so we do so after Karma finishes.
287 export HOME=$(mktemp -d)
288
289 readonly COMMAND="${{KARMA}} "start" ${{CONF}}"
290 ${{COMMAND}}
291 KARMA_EXIT_CODE=$?
292 echo "Karma returned ${{KARMA_EXIT_CODE}}"
293 # Attempt to clean up the temporary home directory. If this fails, that's not a big deal because
294 # the contents are small and will be cleaned up by the OS on reboot.
295 rm -rf $HOME || true
296 exit $KARMA_EXIT_CODE
297 """
298
299 def _create_bash_script_to_invoke_karma(ctx):
300 ctx.actions.write(
301 output = ctx.outputs.executable,
302 is_executable = True,
303 content = _invoke_karma_bash_script.format(
304 _KARMA_EXECUTABLE_SCRIPT = _absolute_path(ctx, ctx.executable.karma),
305 _KARMA_CONFIGURATION_FILE = _absolute_path(ctx, ctx.outputs.configuration),
306 ),
307 )
308
309 def _karma_test_impl(ctx):
310 _expand_templates_in_karma_config(ctx)
311 _create_bash_script_to_invoke_karma(ctx)
312
313 # The files that need to be included when we run the bash script that invokes Karma are:
314 # - The templated configuration file
315 # - Any JS test files the user provided
316 # - Any static files the user specified
317 runfiles = [
318 ctx.outputs.configuration,
319 ]
320 runfiles += ctx.files.srcs
321 runfiles += ctx.files.static_files
322
323 # Now we combine this with the files necessary to run Karma
324 # (which includes the plugins as data dependencies).
325 karma_files = ctx.attr.karma[DefaultInfo].default_runfiles
326
327 # https://bazel.build/rules/lib/builtins/ctx#runfiles
328 combined_runfiles = ctx.runfiles(files = runfiles).merge(karma_files)
329
330 # https://bazel.build/rules/lib/providers/DefaultInfo
331 return [DefaultInfo(
332 runfiles = combined_runfiles,
333 executable = ctx.outputs.executable,
334 )]
335
336 _karma_test = rule(
337 implementation = _karma_test_impl,
338 test = True,
339 executable = True,
340 attrs = {
341 "config_file": attr.label(
342 doc = "The karma config file",
343 mandatory = True,
344 allow_single_file = [".js"],
345 ),
346 "srcs": attr.label_list(
347 doc = "A list of JavaScript test files",
348 allow_files = [".js"],
349 mandatory = True,
350 ),
351 "karma": attr.label(
352 doc = "karma binary label",
353 # By default, we use the karma pulled in via Bazel running npm install
354 # that has extra data dependencies for the necessary plugins.
355 default = "//bazel/karma:karma_with_plugins",
356 executable = True,
357 cfg = "exec",
358 allow_files = True,
359 ),
360 "static_files": attr.label_list(
361 doc = "Additional files which are available to be loaded",
362 allow_files = True,
363 ),
364 },
365 outputs = {
366 "configuration": "%{name}.conf.js",
367 },
368 )