BTest

https://github.com/zeek/btest
Admin
BTest is a powerful, straightforward framework for writing and executing shell-based system tests,...
Tokens:19,433
Snippets:193
Trust Score:9.5
License:BSD-3-Clause
Update:10 months ago
Show doc for...
Tokens:
Raw
### Install BTest from source tarball

Source: https://github.com/zeek/btest/blob/master/README.rst

Installs BTest by downloading and extracting a source tarball, then running the setup script. This method is useful for offline installations or when working directly from source.

```bash
> tar xzvf btest-*.tar.gz
> cd btest-*
> python3 setup.py install

```

--------------------------------

### Install BTest using pip

Source: https://github.com/zeek/btest/blob/master/README.rst

Installs the BTest framework using pip, the Python package installer. This is the recommended method for installation.

```bash
> pip install btest

```

--------------------------------

### btest Configuration File Example

Source: https://github.com/zeek/btest/blob/master/README.rst

Example of a btest configuration file ('btest.cfg') demonstrating the use of DEFAULT and environment sections. This allows setting default values and environment variables for test execution.

```ini
[DEFAULT]
val=abcd

[environment]
ENV_VALUE=%(val)s
```

--------------------------------

### BTest Configuration File Example

Source: https://github.com/zeek/btest/blob/master/README.rst

Example configuration for btest.cfg, including specifying test directories and a finalizer. The 'PartFinalizer' option is set to 'btest-diff-rst'.

```ini
[btest]
...
TestDirs=doc/
PartFinalizer=btest-diff-rst
```

--------------------------------

### Install BTest Scripts with CMake

Source: https://github.com/zeek/btest/blob/master/CMakeLists.txt

This CMake code snippet installs various BTest executable scripts and Sphinx-related documentation files to the 'bin' directory. It uses the 'install(PROGRAMS)' command, which is suitable for installing executable files.

```cmake
cmake_minimum_required(VERSION 3.15.0 FATAL_ERROR)
project(btest)

# Install scripts
install(DIRECTORY DESTINATION bin)
install(PROGRAMS
    btest
    btest-ask-update
    btest-bg-run
    btest-bg-run-helper
    btest-bg-wait
    btest-diff
    btest-setsid
    btest-progress
    sphinx/btest-diff-rst
    sphinx/btest-rst-cmd
    sphinx/btest-rst-include
    sphinx/btest-rst-pipe
    DESTINATION bin)
```

--------------------------------

### Create and Verify Output Baselines (Shell)

Source: https://github.com/zeek/btest/blob/master/README.rst

Shows how to use BTest to create and verify output baselines. It involves running a command to generate output, diffing it against a baseline, and handling updates and diagnostics. The example uses awk to list dot files and btest-diff for comparison.

```shell
# @TEST-EXEC: ls -a $HOME | awk -f %INPUT >dots
# @TEST-EXEC: btest-diff dots
/\^\.+/ { print $1 }
```

```shell
> btest -U examples/t4.awk
```

```shell
> btest examples/t4.awk
```

```shell
> btest -d examples/t4.awk
```

```shell
> rm ~/.NEWDOTFILE
> btest -d examples/t4.awk
```

--------------------------------

### BTest test using input file as script

Source: https://github.com/zeek/btest/blob/master/README.rst

This BTest example executes the test file itself as a shell script. The '# @TEST-EXEC: sh %INPUT' line tells BTest to run the file content via 'sh'.

```bash
cat examples/t3.sh
# @TEST-EXEC: sh %INPUT
ls /etc | grep -q passwd

```

--------------------------------

### Display BTest Build Summary with CMake

Source: https://github.com/zeek/btest/blob/master/CMakeLists.txt

This CMake snippet displays a summary of the BTest build configuration, including the installation prefix and the Python module installation path. It uses the 'message' command to output informational text to the console during the build process.

```cmake
message(
    "\n====================|  BTest Build Summary  |==================="
    "\n"
    "\nInstall prefix:      ${CMAKE_INSTALL_PREFIX}"
    "\nPython module path:  ${PY_MOD_INSTALL_DIR}"
    "\n"
    "\n================================================================\n"
)
```

--------------------------------

### BTest simple test execution

Source: https://github.com/zeek/btest/blob/master/README.rst

A basic BTest example where commands are prefixed with '@TEST-EXEC:'. The test passes if all commands return a success exit code.

```bash
cat examples/t1
@TEST-EXEC: echo "Foo" | grep -q Foo
@TEST-EXEC: test -d .

```

--------------------------------

### Run BTest using configuration file

Source: https://github.com/zeek/btest/blob/master/README.rst

Executes BTest tests based on the configuration defined in its configuration file. This allows for more complex testsuite setups and automatic scanning of directories specified in the config.

```bash
> btest

```

--------------------------------

### Run Background Processes and Wait for Completion

Source: https://context7.com/zeek/btest/llms.txt

Spawn processes in the background and wait for them to complete execution. This is useful for testing services or daemons that run asynchronously. The `btest-bg-run` command starts a process, and `btest-bg-wait` ensures it finishes within a specified timeout.

```bash
cat > bg-test << 'EOF'\n# @TEST-EXEC: btest-bg-run server "netcat -l 8080 >output"\n# @TEST-EXEC: sleep 1\n# @TEST-EXEC: echo "data" | netcat localhost 8080\n# @TEST-EXEC: btest-bg-wait 10\n# @TEST-EXEC: btest-diff server/output\nEOF\n
btest bg-test
```

--------------------------------

### BTest test execution with failure

Source: https://github.com/zeek/btest/blob/master/README.rst

An example of a BTest that fails because one of the '@TEST-EXEC:' commands returns a non-success exit code.

```bash
cat examples/t2
@TEST-EXEC: echo "Foo" | grep -q Foo
@TEST-EXEC: test -d DOESNOTEXIST

```

--------------------------------

### Define Input Filters for BTest Commands

Source: https://github.com/zeek/btest/blob/master/README.rst

Create filters to modify input files before they are used by test commands. A filter is defined in an `[filter-<name>]` section, mapping a command name to a filter script. The script receives input and output file paths as arguments. For example, `cat=%(testbase)s/bin/filter-cat` uses a script to process the input for the `cat` command.

```ini
[filter-myalternative]
cat=%(testbase)s/bin/filter-cat
```

--------------------------------

### Install BTest Python Module with CMake

Source: https://github.com/zeek/btest/blob/master/CMakeLists.txt

This CMake code configures the installation of the BTest Python module. It sets the installation directory for Python modules, defaulting to 'lib/python' if not already defined. It then installs the Python module directory and a specific Python script.

```cmake
if ( NOT PY_MOD_INSTALL_DIR )
    # This is not a Zeek-bundled install, from which we'd inherit that
    # variable.  Default to "home"-style install.
    set(PY_MOD_INSTALL_DIR lib/python)
endif ()

# Install the Python module
install(DIRECTORY DESTINATION ${PY_MOD_INSTALL_DIR})
install(FILES sphinx/btest-sphinx.py DESTINATION ${PY_MOD_INSTALL_DIR})
```

--------------------------------

### BTest Command Line Options (Shell)

Source: https://github.com/zeek/btest/blob/master/README.rst

Provides an overview of common command-line options for the 'btest' command. This includes options for activating alternative configurations, showing all test results, and running tests in brief mode.

```shell
btest -a ALTERNATIVE, --alternative=ALTERNATIVE
btest -A, --show-all
btest -b, --brief
```

--------------------------------

### Create and Verify Output Baselines

Source: https://context7.com/zeek/btest/llms.txt

Establish baselines for command output using the '-U' flag during the first run. Subsequent runs compare against these baselines, failing if discrepancies are found. This requires a test command that produces output to be captured.

```bash
# Create test that produces output to verify
cat > output-test.awk << 'EOF'
# @TEST-EXEC: ls -a $HOME | awk -f %INPUT >dots
# @TEST-EXEC: btest-diff dots
/^.+/ { print $1 }
EOF

# First run: establish baseline with -U flag
btest -U output-test.awk
# Output: output-test ... ok
# Creates Baseline/output-test/dots

# Subsequent runs compare against baseline
btest output-test.awk
# Output: output-test ... ok

# If output changes, test fails
touch ~/.NEWFILE
btest output-test.awk
# Output: output-test ... failed
```

--------------------------------

### Execute Echo Command and Capture Output (None)

Source: https://github.com/zeek/btest/blob/master/examples/sphinx/index.md

This snippet demonstrates executing a simple 'echo' command and capturing its standard output. It's useful for verifying basic command execution and output. The 'none' language tag indicates no specific language processing is applied.

```none
# echo Hello, world!
Hello, world!
```

```none
# echo Hello, world! Again.
Hello, world! Again.
```

```none
# echo Hello, world! Again. Again.
Hello, world! Again. Again.
```

```none
# echo This succeeds again!
This succeeds again!
```

```none
# echo This succeeds again!
This succeeds again!
```

--------------------------------

### Run Tests with Alternative Configurations

Source: https://context7.com/zeek/btest/llms.txt

Execute tests using different build configurations, such as 'debug' or 'optimized' builds. This allows for testing the same test suite against various build types to ensure consistency and performance.

```bash
btest --alternative=debug,optimized tests/
```

--------------------------------

### btest Command-Line Options

Source: https://github.com/zeek/btest/blob/master/README.rst

Command-line options to control btest execution. These include interactive waiting, XML reporting, test retries, and specifying test files.

```bash
-w, --wait
    Interactively waits for ``<enter>`` after showing diagnostics
    for a test.

-x FILE, --xml=FILE
    Records test results in JUnit XML format to the given file.
    If the file exists already, it is overwritten.

-z RETRIES, --retries=RETRIES
    Retry any failed tests up to this many times to determine if
    they are unstable.

-i FILE, --tests-file=FILE
    Loads the list of tests to execute from a file. Each line in the
    file is interpreted as the name of a test, or a group of tests, to
    execute, just like the tests would be specified on the command
    line. Empty lines and lines starting with ``#`` are ignored. (This
    format is compatible with that of the ``btest`` `StateFile
    <state_file_>`_.)
```

--------------------------------

### Execute Shell Command and Verify Output

Source: https://github.com/zeek/btest/blob/master/testing/Baseline/tests.sphinx.run-sphinx/_build.text.index.txt

This snippet demonstrates executing a simple shell command 'echo' and verifying its standard output. It's a basic test case used to confirm command execution and output capture within the BTest framework. No external dependencies are required beyond a standard shell environment.

```shell
# echo Hello, world!
Hello, world!

# echo Hello, world! Again.
Hello, world! Again.

# echo Hello, world! Again. Again.
Hello, world! Again. Again.

# echo This will fail soon!
This will fail soon!
```

--------------------------------

### Basic BTest Configuration File

Source: https://context7.com/zeek/btest/llms.txt

A `btest.cfg` file can be used to configure BTest settings such as test directories, temporary directories, baseline locations, and environment variables. The framework automatically detects and uses this file.

```ini
# btest.cfg
[btest]
TestDirs = tests
TmpDir = .tmp
BaselineDir = Baseline

[environment]
PATH = %(testbase)s/bin:%(default_path)s
TEST_VAR = myvalue
```

```bash
# Run tests using configuration
btest
# Automatically finds btest.cfg and runs all TestDirs
```

--------------------------------

### Generate Chrome Tracing Format for Performance Visualization

Source: https://context7.com/zeek/btest/llms.txt

Create a trace file in JSON format that can be loaded into Chrome's tracing tool (`chrome://tracing`). This is useful for visualizing test execution performance and identifying bottlenecks.

```bash
btest --trace-file trace.json tests/

# View in Chrome browser at chrome://tracing
# Or convert to HTML:
# trace2html trace.json --output trace.html
```

--------------------------------

### Run Simple Shell Command Tests

Source: https://context7.com/zeek/btest/llms.txt

Execute shell commands prefixed with '@TEST-EXEC:' and verify their exit codes. This is the most basic way to write tests in BTest.

```bash
# Create a basic test file
cat > my-test.sh << 'EOF'
@TEST-EXEC: echo "Hello World" | grep -q Hello
@TEST-EXEC: test -f /etc/hosts
EOF

# Run the test
btest my-test.sh
# Output: my-test ... ok
```

--------------------------------

### BTest Test File Keywords

Source: https://github.com/zeek/btest/blob/master/README.rst

Illustrates BTest keywords used in test files to control test execution and behavior. These keywords include directives for running tests with specific alternatives, copying files, associating documentation, and executing commands.

```plaintext
@TEST-ALTERNATIVE: <alternative>
@TEST-COPY-FILE: <file>
@TEST-DOC: <docstring>
@TEST-EXEC: <cmdline>
```

--------------------------------

### Implement Command Line Substitutions in BTest

Source: https://github.com/zeek/btest/blob/master/README.rst

Configure substitutions to replace specific commands or parts of command lines within BTest tests. Defined in `[substitution-<name>]` sections, these map an original command (or string) to its replacement. For instance, `gcc=gcc -O2` replaces all occurrences of `gcc` with `gcc -O2` on the command line.

```ini
[substitution-myalternative]
gcc=gcc -O2
```

--------------------------------

### Execute Test Script and Check Return Value (Shell)

Source: https://github.com/zeek/btest/blob/master/README.rst

Demonstrates executing a shell script test using the @TEST-EXEC keyword and verifying its return value. This highlights that @TEST-EXEC can be placed within comments.

```shell
# @TEST-EXEC: some_command
# Check return value of some_command
```

--------------------------------

### Run BTest on a test suite directory

Source: https://github.com/zeek/btest/blob/master/README.rst

Executes all BTest tests found within the specified directory. BTest will scan the directory for test files and run them.

```bash
> btest ./testsuite/

```

--------------------------------

### Organize and Select Tests Using Groups

Source: https://context7.com/zeek/btest/llms.txt

Group tests using the `# @TEST-GROUP:` directive and selectively run them using the `-g` flag. This allows for categorizing tests (e.g., 'quick', 'slow', 'integration') and running specific subsets.

```bash
# Tests with groups
cat > test1 << 'EOF'\n# @TEST-GROUP: quick\n# @TEST-EXEC: echo "fast test"\nEOF\n
cat > test2 << 'EOF'\n# @TEST-GROUP: slow\n# @TEST-GROUP: integration\n# @TEST-EXEC: sleep 2 && echo "slow test"\nEOF\n
# Run only quick tests
btest -g quick tests/

# Run all except slow tests
btest -g -slow tests/

# Run multiple groups
btest -g quick,integration tests/
```

--------------------------------

### Define Multiple Zeek BTests in One File

Source: https://github.com/zeek/btest/blob/master/README.rst

Enables the definition of multiple tests within a single file using the @TEST-START-NEXT keyword. Each section separated by @TEST-START-NEXT is treated as a distinct test, executing the same commands with different inputs. BTest automatically appends suffixes like '-2' to enumerate these tests.

```zeek
# @TEST-EXEC: cat %INPUT | wc -c >output
# @TEST-EXEC: btest-diff output

This is the first test input in this file.

# @TEST-START-NEXT

... and the second.

```

--------------------------------

### Run a specific BTest file

Source: https://github.com/zeek/btest/blob/master/README.rst

Executes a single, specified BTest file. This is useful for running individual tests or debugging specific test cases.

```bash
> btest ./testsuite/my.test

```

--------------------------------

### BTest Configuration File (Ini)

Source: https://github.com/zeek/btest/blob/master/examples/sphinx/index.md

This snippet shows a BTest configuration file ('btest.cfg') in INI format. It defines test directories, temporary directories, baseline directories, and environment variables. This file is essential for configuring BTest behavior.

```ini
[btest]
TestDirs    = tests
TmpDir      = %(testbase)s/.tmp
BaselineDir = %(testbase)s/Baseline
Finalizer   = btest-diff-rst

[environment]
PATH=%(testbase)s/../../:%(testbase)s/../../sphinx:%(default_path)s
```

--------------------------------

### btest Configuration Options

Source: https://github.com/zeek/btest/blob/master/README.rst

Options that can be set in the 'btest' section of the btest configuration file to customize behavior. These include baseline directory, command prefix, finalizers, and directories/files to ignore.

```ini
``BaselineDir``
    One or more directories where to store the baseline files for
    ``btest-diff`` (note that the actual baseline files will be placed
    into test-specific subdirectories of this directory).  By default,
    this is set to ``%(testbase)s/Baseline``.

    If multiple directories are to be used, they must be separated by
    colons. ``btest-diff`` will then search them for baseline files in
    order when looking for a baseline to compare against. When
    updating a baseline, it will always store the new version inside
    the first directory. Using multiple directories is most useful in
    combination with alternatives_ to support alternate executions
    where some tests produce expected differences in their output.

    This option can also be set through an environment variable
    ``BTEST_BASELINE_DIR``.

``CommandPrefix``
    Changes the naming of all ``btest`` commands by replacing the
    ``@TEST-`` prefix with a custom string. For example, with
    ``CommandPrefix=$TEST-``, the ``@TEST-EXEC`` command becomes
    ``$TEST-EXEC``.

``Finalizer``
    A command that will be executed each time any test has
    successfully run. It runs in the same directory as the test itself
    and receives the name of the test as its only argument. The return
    value indicates whether the test should indeed be considered
    successful. By default, there's no finalizer set.

``IgnoreDirs``
    A space-separated list of relative directory names to ignore
    when scanning test directories recursively. Default is empty.

    An alternative way to ignore a directory is placing a file
    ``.btest-ignore`` in it.

``IgnoreFiles``
    A space-separated list of filename globs matching files to
    ignore when scanning given test directories recursively.
```

--------------------------------

### Configure Sphinx Integration for BTest

Source: https://github.com/zeek/btest/blob/master/README.rst

Configuration settings for BTest's Sphinx extension. Specifies the base directory for BTest configuration and the directory to store extracted tests. Requires 'btest-sphinx' in Sphinx extensions.

```python
extensions += ["btest-sphinx"]
btest_base="tests"         # Relative to Sphinx-root.
btest_tests="doc"          # Relative to btest_base.
```

--------------------------------

### Configure Environment Variables for BTest Alternatives

Source: https://github.com/zeek/btest/blob/master/README.rst

Define environment variables that will be available to commands executed within a BTest alternative. You can add variables by specifying `VARIABLE=value` or remove them by prefixing with `-` (e.g., `-CFLAGS`). This allows customizing the testing environment.

```ini
[environment-myalternative]
CFLAGS=-O3
-DEBUG=
```

--------------------------------

### Split Single Test Across Multiple Files (Test Parts)

Source: https://context7.com/zeek/btest/llms.txt

Distribute parts of a single test across multiple files that share the same sandbox environment. Each file is treated as a part of the same test, allowing for modular test development and execution where output accumulates across parts.

```bash
# part1.sh#1
cat > test-parts.sh#1 << 'EOF'\n# @TEST-EXEC: echo "Part 1" >>output\nEOF\n
# part1.sh#2
cat > test-parts.sh#2 << 'EOF'\n# @TEST-EXEC: echo "Part 2" >>output\nEOF\n
# part1.sh#3
cat > test-parts.sh#3 << 'EOF'\n# @TEST-EXEC: btest-diff output\nEOF\n
btest test-parts.sh
```

--------------------------------

### Use %INPUT Macro for Script Tests

Source: https://context7.com/zeek/btest/llms.txt

The %INPUT macro allows the test file itself to be used as input to a command, typically a script. This is useful for testing scripts that process their own content or arguments.

```bash
# Create a shell script test
cat > script-test.sh << 'EOF'
# @TEST-EXEC: sh %INPUT
ls /etc | grep -q passwd
EOF

# Execute the test - the script itself becomes input
btest script-test.sh
# Output: script-test ... ok
```

--------------------------------

### Run Tests from a Directory

Source: https://context7.com/zeek/btest/llms.txt

BTest can execute all test files within a specified directory recursively. This is useful for organizing larger test suites.

```bash
# Create a test suite directory
mkdir -p tests
echo '@TEST-EXEC: echo "test1" | grep -q test1' > tests/t1
echo '@TEST-EXEC: echo "test2" | grep -q test2' > tests/t2

# Run all tests in directory
btest tests/
# Output:
# tests.t1 ... ok
# tests.t2 ... ok
```

--------------------------------

### Generate Test Documentation in Markup Format

Source: https://context7.com/zeek/btest/llms.txt

Extract documentation embedded within test files using `# @TEST-DOC:` directives and generate it in various markup formats like reStructuredText (`rst`) or Markdown (`md`). This helps in automatically generating documentation from test cases.

```bash
# Tests with documentation
cat > documented-test << 'EOF'\n# @TEST-DOC: Verifies user authentication flow
# @TEST-DOC: Tests both valid and invalid credentials
# @TEST-EXEC: test-auth.sh\nEOF\n
# Generate reStructuredText documentation
btest -R rst tests/ > tests.rst

# Generate Markdown documentation
btest -R md tests/ > tests.md
```

--------------------------------

### BTest Alternative Configurations

Source: https://context7.com/zeek/btest/llms.txt

BTest supports defining and activating alternative configurations for tests, specified in `btest.cfg`. These can modify environment variables, command substitutions, and filters for specific test runs, such as a 'debug' configuration.

```ini
# btest.cfg with alternative
[environment-debug]
BUILD_TYPE = debug
CFLAGS = -g -O0

[substitution-debug]
gcc = gcc -g -O0

[filter-debug]
cat = /path/to/filter-script
```

```bash
# Run tests with alternative configuration
btest --alternative=debug tests/
```

--------------------------------

### Verify Successful Shell Command Execution

Source: https://github.com/zeek/btest/blob/master/testing/Baseline/tests.sphinx.run-sphinx/_build.text.index.txt

This snippet demonstrates a successful execution of a shell command within the BTest framework. It shows the command being executed and its expected output, confirming that the test case passed as anticipated. This is used for validating expected behavior.

```shell
# echo This succeeds again!
This succeeds again!

# echo This succeeds again!
This succeeds again!
```

--------------------------------

### Display Test Progress (btest-progress)

Source: https://github.com/zeek/btest/blob/master/README.rst

Helps display progress messages during long-running tests. Accepts a custom message as an argument and displays it in real-time. The '-q' option can suppress printing messages to stdout/stderr.

```bash
# @TEST-EXEC: bash %INPUT

btest-progress Stage 1
sleep 1
btest-progress Stage 2
sleep 1
btest-progress Stage 3
sleep 1
```

```bash
btest-progress -q "Skipping step"
```

--------------------------------

### Abort on First Failure (Bash)

Source: https://context7.com/zeek/btest/llms.txt

Stops test execution immediately when the first test fails. The `-F` flag activates this behavior, making it ideal for CI/CD pipelines where quick feedback on the initial failure is crucial.

```bash
btest -F tests/
# Output:
tests.t1 ... ok
tests.t2 ... failed
Aborted after first failure.

# Useful for CI/CD pipelines
```

--------------------------------

### Configure Baseline Canonification Script

Source: https://context7.com/zeek/btest/llms.txt

Define a script to filter baseline output, removing variable content like timestamps and process IDs. This canonifier is set using the `TEST_DIFF_CANONIFIER` environment variable, ensuring that baseline comparisons ignore such dynamic elements.

```bash
# Create canonifier script
cat > canonify.sh << 'EOF'\n#!/bin/bash
# Remove timestamps and process IDs
sed 's/[0-9]\{4\}-[0-9]\{2\}-[0-9]\{2\} [0-9:]\+//g' | \
sed 's/pid=[0-9]\+/pid=XXXXX/g'
EOF
chmod +x canonify.sh

# Set in test or environment
export TEST_DIFF_CANONIFIER=./canonify.sh

# Now baselines ignore timestamps and PIDs
btest -U test-with-timestamps.sh
```

--------------------------------

### Define Multiple Test Inputs in a Single File

Source: https://context7.com/zeek/btest/llms.txt

Define multiple distinct test inputs within a single test file. Each input section is separated by `# @TEST-START-NEXT`, allowing for multiple executions of the same test script with different data.

```bash
cat > multi-test.sh << 'EOF'\n# @TEST-EXEC: cat %INPUT | wc -c >output\n# @TEST-EXEC: btest-diff output\n
This is the first test input.\n
# @TEST-START-NEXT\n
This is the second test input.\nEOF\n
btest multi-test.sh
```

--------------------------------

### Include External File in Zeek BTest

Source: https://github.com/zeek/btest/blob/master/README.rst

Defines an external file to be included as input for a test. Lines between @TEST-START-FILE and @TEST-END-FILE are written to the specified file and removed from the test's main input. Supports multiple include files within a single test.

```zeek
# @TEST-EXEC: awk -f %INPUT <foo.dat >output
# @TEST-EXEC: btest-diff output

    { lines += 1; }
END { print lines; }

@TEST-START-FILE foo.dat
1
2
3
@TEST-END-FILE

```

--------------------------------

### Run Tests in Parallel

Source: https://context7.com/zeek/btest/llms.txt

BTest supports parallel test execution to speed up test suites. The '-j' flag specifies the number of parallel threads, or can be used without an argument to utilize all available CPU cores.

```bash
# Run with 4 threads
btest -j 4 tests/

# Use all available CPU cores
btest -j tests/

# Output includes thread numbers:
# [#1] tests.t1 ... ok
# [#2] tests.t2 ... ok
# [#3] tests.t3 ... ok
```

--------------------------------

### Serialize Test Execution

Source: https://context7.com/zeek/btest/llms.txt

The '@TEST-SERIALIZE:' directive in test files ensures that tests with the same key are executed sequentially, even when parallel execution is enabled. This is essential for tests that share resources like databases.

```bash
# Test file with serialization
cat > exclusive-test << 'EOF'
# @TEST-SERIALIZE: database
# @TEST-EXEC: use-shared-database.sh
# Tests with same serialize key run sequentially
EOF

# These tests won't run simultaneously even with -j
btest -j 8 tests/
```

--------------------------------

### Wait for Background Processes (btest-bg-wait)

Source: https://github.com/zeek/btest/blob/master/README.rst

Waits for previously spawned processes via 'btest-bg-run' to finish. Exits with a non-zero code if any process fails. Supports a timeout and a '-k' option to ignore non-termination failures.

```bash
btest-bg-wait <timeout>
```
Tokens:
Raw