blob: fb79d737d8ac8f27fe106001e2eeb74bb397484d [file] [log] [blame]
"""This module defines rules for running JS tests in a browser."""
load("@build_bazel_rules_nodejs//:providers.bzl", "ExternalNpmPackageInfo", "node_modules_aspect")
# https://github.com/bazelbuild/rules_webtesting/blob/master/web/web.bzl
load("@io_bazel_rules_webtesting//web:web.bzl", "web_test")
# https://github.com/google/skia-buildbot/blob/main/bazel/test_on_env/test_on_env.bzl
load("@org_skia_go_infra//bazel/test_on_env:test_on_env.bzl", "test_on_env")
def karma_test(name, config_file, srcs, static_files = None, env = None, **kwargs):
"""Tests the given JS files using Karma and a browser provided by Bazel (Chromium)
This rule injects some JS code into the karma config file and produces both that modified
configuration file and a bash script which invokes Karma. That script is then invoked
in an environment that has the Bazel-downloaded browser available and the tests run using it.
When invoked via `bazel test`, the test runs in headless mode. When invoked via `bazel run`,
a visible web browser appears for the user to inspect and debug.
This draws inspiration from the karma_web_test implementation in concatjs
https://github.com/bazelbuild/rules_nodejs/blob/700b7a3c5f97f2877320e6e699892ee706f85269/packages/concatjs/web_test/karma_web_test.bzl
but we were unable to use it because they prevented us from defining some proxies ourselves,
which we need in order to communicate our test gms (PNG files) to a server that runs alongside
the test. This implementation is simpler than concatjs's and does not try to work for all
situations nor bundle everything together.
Args:
name: The name of the rule which actually runs the tests. generated dependent rules will use
this name plus an applicable suffix.
config_file: A karma config file. The user is to expect a function called BAZEL_APPLY_SETTINGS
is defined and should call it with the configuration object before passing it to config.set.
srcs: A list of JavaScript test files or helpers.
static_files: Arbitrary files which are available to be loaded.
Files are served at:
- `/static/<WORKSPACE_NAME>/<path-to-file>` or
- `/static/<WORKSPACE_NAME>/<path-to-rule>/<file>`
Examples:
- `/static/skia/modules/canvaskit/tests/assets/color_wheel.gif`
- `/static/skia/modules/canvaskit/canvaskit_wasm/canvaskit.wasm`
env: An optional label to a binary. If set, the test will be wrapped in a test_on_env rule,
and this binary will be used as the "env" part of test_on_env. It will be started before
the tests run and be running in parallel to them. See the test_on_env.bzl in the
Skia Infra repo for more.
**kwargs: Additional arguments are passed to @io_bazel_rules_webtesting/web_test.
"""
if len(srcs) == 0:
fail("Must pass at least one file into srcs or there will be no tests to run")
if not static_files:
static_files = []
karma_test_name = name + "_karma_test"
_karma_test(
name = karma_test_name,
srcs = srcs,
deps = [
"@npm//karma-chrome-launcher",
"@npm//karma-firefox-launcher",
"@npm//karma-jasmine",
"@npm//jasmine-core",
],
config_file = config_file,
static_files = static_files,
visibility = ["//visibility:private"],
tags = ["manual"],
)
# See the following link for the options.
# https://github.com/bazelbuild/rules_webtesting/blob/e9cf17123068b1123c68219edf9b274bf057b9cc/web/internal/web_test.bzl#L164
# TODO(kjlubick) consider using web_test_suite to test on Firefox as well.
if not env:
web_test(
name = name,
launcher = ":" + karma_test_name,
browser = "@io_bazel_rules_webtesting//browsers:chromium-local",
test = karma_test_name,
**kwargs
)
else:
web_test_name = name + "_web_test"
web_test(
name = web_test_name,
launcher = ":" + karma_test_name,
browser = "@io_bazel_rules_webtesting//browsers:chromium-local",
test = karma_test_name,
visibility = ["//visibility:private"],
**kwargs
)
test_on_env(
name = name,
env = env,
test = ":" + web_test_name,
test_on_env_binary = "@org_skia_go_infra//bazel/test_on_env:test_on_env",
)
# This JS code is injected into the the provided karma configuration file. It contains
# Bazel-specific logic that could be re-used across different configuration files.
# Concretely, it sets up the browser configuration and whether we want to just run the tests
# and exit (e.g. the user ran `bazel test foo`) or if we want to have an interactive session
# (e.g. the user ran `bazel run foo`).
_apply_bazel_settings_js_code = """
(function(cfg) {
// This is is a JS function provided via environment variables to let us resolve files
// https://bazelbuild.github.io/rules_nodejs/Built-ins.html#nodejs_binary-templated_args
const runfiles = require(process.env['BAZEL_NODE_RUNFILES_HELPER']);
// Apply the paths to any files that are coming from other Bazel rules (e.g. compiled JS).
function addFilePaths(cfg) {
if (!cfg.files) {
cfg.files = [];
}
cfg.files = cfg.files.concat([_BAZEL_SRCS]);
cfg.basePath = "_BAZEL_BASE_PATH";
if (!cfg.proxies) {
cfg.proxies = {};
}
// The following is based off of the concatjs version
// https://github.com/bazelbuild/rules_nodejs/blob/700b7a3c5f97f2877320e6e699892ee706f85269/packages/concatjs/web_test/karma.conf.js#L276
const staticFiles = [_BAZEL_STATIC_FILES];
for (const file of staticFiles) {
// We need to find the actual path (symlinks can apparently cause issues on Windows).
const resolvedFile = runfiles.resolve(file);
cfg.files.push({pattern: resolvedFile, included: false});
// We want the file to be available on a path according to its location in the workspace
// (and not the path on disk), so we use a proxy to redirect.
// Prefixing the proxy path with '/absolute' allows karma to load files that are not
// underneath the basePath. This doesn't see to be an official API.
// https://github.com/karma-runner/karma/issues/2703
cfg.proxies['/static/' + file] = '/absolute' + resolvedFile;
}
}
// Returns true if invoked with bazel run, i.e. the user wants to see the results on a real
// browser.
function isBazelRun() {
// This env var seems to be a good indicator on Linux, at least.
return !!process.env['DISPLAY'];
}
// Configures the settings to run chrome.
function applyChromiumSettings(cfg, chromiumPath) {
if (isBazelRun()) {
cfg.browsers = ['Chrome'];
cfg.singleRun = false;
} else {
// Invoked via bazel test, so run the tests once in a headless browser and be done
cfg.browsers = ['ChromeHeadless'];
cfg.singleRun = true;
}
try {
// Setting the CHROME_BIN environment variable tells Karma which chrome to use.
// We want it to use the Chrome brought via Bazel.
process.env.CHROME_BIN = runfiles.resolve(chromiumPath);
} catch {
throw new Error(`Failed to resolve Chromium binary '${chromiumPath}' in runfiles`);
}
}
function applyBazelSettings(cfg) {
addFilePaths(cfg)
// This is a JSON file that contains this metadata, mixed in with some other data, e.g.
// the link to the correct executable for the given platform.
// https://github.com/bazelbuild/rules_webtesting/blob/e9cf17123068b1123c68219edf9b274bf057b9cc/browsers/chromium-local.json
const webTestMetadata = require(runfiles.resolve(process.env['WEB_TEST_METADATA']));
const webTestFiles = webTestMetadata['webTestFiles'][0];
const path = webTestFiles['namedFiles']['CHROMIUM'];
if (path) {
applyChromiumSettings(cfg, path);
} else {
throw new Error("not supported yet");
}
}
applyBazelSettings(cfg)
// The user is expected to treat the BAZEL_APPLY_SETTINGS as a function name and pass in
// the configuration as a parameter. Thus, we need to end such that our IIFE will be followed
// by the parameter in parentheses and get passed in as cfg.
})"""
def _expand_templates_in_karma_config(ctx):
# Wrap the absolute paths of our files in quotes and make them comma seperated so they
# can go in the Karma files list.
srcs = ['"{}"'.format(_absolute_path(ctx, f)) for f in ctx.files.srcs]
src_list = ", ".join(srcs)
# Set our base path to that which contains the karma configuration file.
# This requires going up a few directory segments. This allows our absolute paths to
# all be compatible with each other.
config_segments = len(ctx.outputs.configuration.short_path.split("/"))
base_path = "/".join([".."] * config_segments)
static_files = ['"{}"'.format(_absolute_path(ctx, f)) for f in ctx.files.static_files]
static_list = ", ".join(static_files)
# Replace the placeholders in the embedded JS with those files. We cannot use .format() because
# the curly braces from the JS code throw it off.
apply_bazel_settings = _apply_bazel_settings_js_code.replace("_BAZEL_SRCS", src_list)
apply_bazel_settings = apply_bazel_settings.replace("_BAZEL_BASE_PATH", base_path)
apply_bazel_settings = apply_bazel_settings.replace("_BAZEL_STATIC_FILES", static_list)
# Add in the JS fragment that applies the Bazel-specific settings to the provided config.
# https://docs.bazel.build/versions/main/skylark/lib/actions.html#expand_template
ctx.actions.expand_template(
output = ctx.outputs.configuration,
template = ctx.file.config_file,
substitutions = {
"BAZEL_APPLY_SETTINGS": apply_bazel_settings,
},
)
def _absolute_path(ctx, file):
# Referencing things in @npm yields a short_path that starts with ../
# For those cases, we can just remove the ../
if file.short_path.startswith("../"):
return file.short_path[3:]
# Otherwise, we have a local file, so we need to include the workspace path to make it
# an absolute path
return ctx.workspace_name + "/" + file.short_path
_invoke_karma_bash_script = """#!/usr/bin/env bash
# --- begin runfiles.bash initialization v2 ---
# Copy-pasted from the Bazel Bash runfiles library v2.
# https://github.com/bazelbuild/bazel/blob/master/tools/bash/runfiles/runfiles.bash
set -uo pipefail; f=build_bazel_rules_nodejs/third_party/github.com/bazelbuild/bazel/tools/bash/runfiles/runfiles.bash
source "${{RUNFILES_DIR:-/dev/null}}/$f" 2>/dev/null || \
source "$(grep -sm1 "^$f " "${{RUNFILES_MANIFEST_FILE:-/dev/null}}" | cut -f2- -d' ')" 2>/dev/null || \
source "$0.runfiles/$f" 2>/dev/null || \
source "$(grep -sm1 "^$f " "$0.runfiles_manifest" | cut -f2- -d' ')" 2>/dev/null || \
source "$(grep -sm1 "^$f " "$0.exe.runfiles_manifest" | cut -f2- -d' ')" 2>/dev/null || \
{{ echo>&2 "ERROR: cannot find $f"; exit 1; }}; f=; set -e
# --- end runfiles.bash initialization v2 ---
readonly KARMA=$(rlocation "{_KARMA_EXECUTABLE_SCRIPT}")
readonly CONF=$(rlocation "{_KARMA_CONFIGURATION_FILE}")
# set a temporary directory as the home directory, because otherwise Chrome fails to
# start up, complaining about a read-only file system. This does not get cleaned up automatically
# by Bazel, so we do so after Karma finishes.
export HOME=$(mktemp -d)
readonly COMMAND="${{KARMA}} "start" ${{CONF}}"
${{COMMAND}}
KARMA_EXIT_CODE=$?
echo "Karma returned ${{KARMA_EXIT_CODE}}"
# Attempt to clean up the temporary home directory. If this fails, that's not a big deal because
# the contents are small and will be cleaned up by the OS on reboot.
rm -rf $HOME || true
exit $KARMA_EXIT_CODE
"""
def _create_bash_script_to_invoke_karma(ctx):
ctx.actions.write(
output = ctx.outputs.executable,
is_executable = True,
content = _invoke_karma_bash_script.format(
_KARMA_EXECUTABLE_SCRIPT = _absolute_path(ctx, ctx.executable.karma),
_KARMA_CONFIGURATION_FILE = _absolute_path(ctx, ctx.outputs.configuration),
),
)
def _karma_test_impl(ctx):
_expand_templates_in_karma_config(ctx)
_create_bash_script_to_invoke_karma(ctx)
# The files that need to be included when we run the bash script that invokes Karma are:
# - The templated configuration file
# - Any JS test files the user provided
# - Any static files the user specified
# - The other dependencies from npm (e.g. jasmine-core)
runfiles = [
ctx.outputs.configuration,
]
runfiles += ctx.files.srcs
runfiles += ctx.files.static_files
runfiles += ctx.files.deps
# We need to add the sources for our Karma dependencies as transitive dependencies, otherwise
# things like the karma-chrome-launcher will not be available for Karma to load.
# https://docs.bazel.build/versions/main/skylark/lib/depset.html
node_modules_depsets = []
for dep in ctx.attr.deps:
if ExternalNpmPackageInfo in dep:
node_modules_depsets.append(dep[ExternalNpmPackageInfo].sources)
else:
fail("Not an external npm file: " + dep)
node_modules = depset(transitive = node_modules_depsets)
# https://docs.bazel.build/versions/main/skylark/lib/DefaultInfo.html
return [DefaultInfo(
runfiles = ctx.runfiles(
files = runfiles,
transitive_files = node_modules,
).merge(ctx.attr.karma[DefaultInfo].data_runfiles),
executable = ctx.outputs.executable,
)]
_karma_test = rule(
implementation = _karma_test_impl,
test = True,
executable = True,
attrs = {
"config_file": attr.label(
doc = "The karma config file",
mandatory = True,
allow_single_file = [".js"],
),
"srcs": attr.label_list(
doc = "A list of JavaScript test files",
allow_files = [".js"],
mandatory = True,
),
"deps": attr.label_list(
doc = """Any karma plugins (aka peer deps) required. These are generally listed
in the provided config_file""",
allow_files = True,
aspects = [node_modules_aspect],
mandatory = True,
),
"karma": attr.label(
doc = "karma binary label",
# By default, we use the karma pulled in via Bazel running npm install
default = "@npm//karma/bin:karma",
executable = True,
cfg = "exec",
allow_files = True,
),
"static_files": attr.label_list(
doc = "Additional files which are available to be loaded",
allow_files = True,
),
},
outputs = {
"configuration": "%{name}.conf.js",
},
)