Skip to main content

nodejs_test

A Node.js test, run with the toolchain's Node runtime and no custom loaders. framework decides what runs and what is reported.

Details​

"node" (the default) runs each test file with Node's built-in test runner, node:test (Node 20 or later), in a process of its own. Its test files are the srcs that node --test with no arguments would run: short paths matching **/*.test.<ext>, **/*-test.<ext>, **/*_test.<ext>, **/test-*.<ext>, **/test.<ext> or **/test/**/*.<ext> outside node_modules, where <ext> is js, mjs or cjs, or ts, mts or cts unless node_args turns off type stripping (--no-strip-types or --no-experimental-strip-types). TypeScript needs Node 22.18+, or 22.6+ with --experimental-strip-types. With library, the test file is the entry_point. args cannot be set. Test files running at once prefix each line they print with [<test file>] .

"jest" runs the test files with Jest from test_runner (a nodejs_node_modules target), or the nodejs toolchain's jest. Its test files are the srcs that the Jest config selects, as jest --listTests reports them; library cannot be set. config, a Jest config file, is staged at its short path, and Jest's rootDir defaults to the config file's directory; without it, rootDir is the staged directory. args are passed to Jest, except the watch modes, the flags the adapter sets (--ci, --watchman, --config, --json, --outputFile, --listTests, --runTestsByPath, --testNamePattern) and the flags that change which test files run (--onlyChanged, --onlyFailures, --changedSince, --changedFilesWithAncestor, --lastCommit, --findRelatedTests, --shard), which fail the test.

"vitest" runs the test files with Vitest from test_runner (a nodejs_node_modules target), or the nodejs toolchain's vitest. Its test files are the srcs that the Vitest config selects, as vitest list --filesOnly reports them; library cannot be set. config, a Vitest config file, is staged at its short path and passed with --config; without it, Vitest's own config discovery under the staged directory applies. args are passed to Vitest, except the flags the adapter sets (run, --root, --config, --reporter, --outputFile, --testNamePattern, the --coverage* flags it sets when coverage is collected, and list/--filesOnly/--json) and the flags that change which test files run (--changed, --related, --shard, --dir, --exclude), which fail the test. Without tsconfig, the srcs are staged as they are and Vitest transpiles TypeScript itself; a type error then fails the test, not the build. When TPX coverage collection is active (COVERAGE_COLLECTION_OUTPUT_FILE is set, as it is for targets with the tpx:supports_coverage label), the adapter runs Vitest with --coverage --coverage.reporter=json into COVERAGE_COLLECTION_TMPDIR (or a temporary directory), then writes TPX coverage JSONL to COVERAGE_COLLECTION_OUTPUT_FILE: one {"filepath", "covered_lines", "executable_lines"} object per file (0-based lines, from the Istanbul statementMap), for files under the staged directory outside node_modules. filepath is the path relative to the staged directory, prefixed with coverage_prefix when it is set, so a caller whose staged files mirror a project subtree (for example coverage_prefix = "xplat/wearable/tools/js/core_utils_common") gets paths relative to the repository root. A missing or unreadable coverage report is a run failure.

tsconfig, with "node", "jest" or "vitest", compiles the .ts, .tsx, .mts and .cts srcs (not declarations) together with the toolchain's tsc, as nodejs_library compiles its srcs, against the nodejs_library deps, the third-party trees and the .json srcs they import, then stages each TypeScript source as the file tsc emits for it: its short path with the extension .js, .mjs or .cjs (.js for .tsx, so jsx must not be preserve). A package.json in srcs decides the emitted module format. Test files are then selected among the emitted names (for "jest", the config must match them) but keep their source paths in results. Other srcs are staged as they are. A type error fails the build rather than the test.

The other srcs are helpers, not run, and main cannot be set. Without library, the test fails if no srcs entry is a test file: at analysis with "node", when listing or running with "jest" or "vitest". node_args go to the Node processes running the test files. Each test file gets a result named by its short path (by the entry_point for library), and each test that finishes gets one named <test file> > <describe> > ... > <test>. With "node", a describe block gets one only when it is skipped or fails on its own, and a test that fails only because a subtest failed gets none. Same-named sibling tests share a result name. A test file fails if any of its tests fails. With "jest" or "vitest", it also fails if it fails to load or the runner reports no result for it. With "node", it also fails if its process exits non-zero or before node:test reports the end of the run, or its events cannot be read in full, naming tests that never finished. With "jest", an unsuccessful Jest run with no failed test file, as for a missed coverage threshold, is a run failure. With "vitest", an unsuccessful Vitest run with no failed test file is likewise a run failure.

The test is an external runner test of type js_test. LIST_COMMAND writes one JSON line {"testcase": <test file>} per test file to the file named by an appended --output <file>. TEST_COMMAND runs the test files and tests named by appended --filter <name> arguments (every test file without one) and, when TEST_RESULTS_OUTPUT_FILE is set, writes results there in the test result output spec. A filter names a test file, a describe block (every test in it) or a test, and fails if it matches no test. With "jest", a filter below a test file ignores case. With "vitest", a filter below a test file is matched as a regular expression against the full test name, case-sensitively. With "node", filtering below a test file needs Node 22 or later and cannot select a subtest of a test(). Run on its own, as by buck2 run, the test writes no results and exits non-zero on failure.

"none" runs main, or the library's entry_point, with args and node_args; its exit code is the only result. srcs are helpers.

The [dir] sub-target, present unless main is a directory run with entry_point, is one directory, built as nodejs_binary builds it: a composed node_modules, srcs and main beside it at their short paths, which must not collide, and a root package.json. When library, deps, a third-party tree or a resources dict is involved, or with "jest" or "vitest", the test runs from [dir]; with library, the entry_point runs in the library's package under node_modules. Otherwise, the test files run in place, and files they import relatively must be in srcs to be build inputs. NODE_PATH is never set; one set in env is passed through. The default output is the launcher, a command_alias wrapper script for the target platform that sets env on Unix and Windows. library, entry_point (and its default) and node_modules (unset inherits the trees of library and deps; a list replaces them; [] means none) follow the same rules as nodejs_binary, as do package staging, .d.ts stripping and deps that are not nodejs_library targets, which are data deps staged in [dir]. resources, and with "none" a directory main with entry_point, also follow nodejs_binary. resources that are not staged are hidden inputs of the test command.

Function Signature​

def nodejs_test(
    *,
    name: str,
    default_target_platform: None | str = None,
    target_compatible_with: list[str] = [],
    compatible_with: list[str] = [],
    exec_compatible_with: list[str] = [],
    visibility: list[str | target_name_glob] = [],
    within_view: list[str | target_name_glob] = ["PUBLIC"],
    metadata: OpaqueMetadata = {},
    tests: list[str] = [],
    modifiers: OpaqueMetadata = [],
    _inject_test_env: str = "prelude//test/tools:inject_test_env",
    _nodejs_toolchain: str = "gh_facebook_buck2_shims_meta//:nodejs",
    _remote_test_execution_toolchain: str = "gh_facebook_buck2_shims_meta//:remote_test_execution",
    _target_os_type: str = "prelude//os_lookup/targets:os_lookup",
    _test_adapter: str = "prelude//nodejs/tools:nodejs_test_adapter.cjs",
    _test_toolchain: str = "gh_facebook_buck2_shims_meta//:test",
    args: list[str] = [],
    config: None | str = None,
    contacts: list[str] = [],
    coverage_prefix: None | str = None,
    deps: list[str] = [],
    entry_point: None | str = None,
    env: dict[str, str] = {},
    framework: str = "node",
    labels: list[str] = [],
    library: None | str = None,
    main: None | str = None,
    network_access: None | str = None,
    node_args: list[str] = [],
    node_modules: None | list[str] = None,
    remote_execution: None | str | dict[str, None | bool | int | str | list[dict[str, str]] | dict[str, int | str | list[str] | dict[str, str]]] = None,
    resources: list[str] | dict[str, str] = [],
    srcs: list[str] = [],
    supports_test_execution_caching: bool = False,
    test_rule_timeout_ms: None | int = None,
    test_runner: None | str = None,
    tsconfig: None | str = None,
) -> None

Parameters​

  • name: (required)

    name of the target

  • default_target_platform: (defaults to: None)

    specifies the default target platform, used when no platforms are specified on the command line

  • target_compatible_with: (defaults to: [])

    a list of constraints that are required to be satisfied for this target to be compatible with a configuration

  • compatible_with: (defaults to: [])

    a list of constraints that are required to be satisfied for this target to be compatible with a configuration

  • exec_compatible_with: (defaults to: [])

    a list of constraints that are required to be satisfied for this target to be compatible with an execution platform

  • visibility: (defaults to: [])

    a list of visibility patterns restricting what targets can depend on this one

  • within_view: (defaults to: ["PUBLIC"])

    a list of visibility patterns restricting what this target can depend on

  • metadata: (defaults to: {})

    a key-value map of metadata associated with this target

  • tests: (defaults to: [])

    a list of targets that provide tests for this one

  • modifiers: (defaults to: [])

    an array of modifiers associated with this target

  • contacts: (defaults to: [])

    A list of organizational contacts for this rule. These could be individuals who you would contact in the event of a failure or other issue with the rule.

    contacts = [ 'Joe Sixpack', 'Erika Mustermann' ]

  • labels: (defaults to: [])

    Set of arbitrary strings which allow you to annotate a build rule with tags that can be searched for over an entire dependency tree using buck query().

  • test_rule_timeout_ms: (defaults to: None)

    If set specifies the maximum amount of time (in milliseconds) in which all of the tests in this rule should complete. This overrides the default rule_timeout if any has been specified in .buckconfig .