| """This module defines the test_on_env rule.""" |
| |
| def test_on_env(name, test, env, timeout_secs = 10): |
| """Allows running test targets that require launching a test environment before their execution. |
| |
| The test_on_env rule takes a *_test target and an environment *_binary target as arguments, |
| and carries out the following steps when invoked with "blaze test": |
| |
| 1. Launches the environment binary. |
| 2. Waits until the environment signals that it is ready. |
| 3. Runs the test target. |
| 4. Tears down the environment process by sending it a SIGTERM signal. |
| 5. Reports the results of the test target (pass/fail). |
| |
| The test_on_env runner script sets two environment variables: |
| |
| - ENV_READY_FILE: Path to a "ready file" that the environment must create to signal the test |
| runner that it is ready to accept connections. |
| - ENV_DIR: Path to a temporary directory that can be used to communicate between the environment |
| and the test binaries. |
| |
| Requirements: |
| - The environment binary must create the $ENV_READY_FILE as soon as it is ready, otherwise the |
| test_on_env runner will wait "forever", eventually timing out and failing. |
| - Any TCP ports open by the environment binary must be chosen by the OS (i.e. no hardcoded port |
| numbers), otherwise tests running in parallel might interfere with each other and cause |
| non-deterministic test failures. |
| |
| Optional: |
| - The $ENV_DIR directory can be used to communicate between the environment and test binaries. |
| A typical use case is for the environment to create an $ENV_DIR/port file containing a TCP |
| port number chosen by the OS. |
| |
| Some examples of tests that might require an environment include: Puppeteer tests, where the |
| environment can be a demo page server (for screenshot tests) or a web application server (for |
| integration tests); integration tests for a command-line tool that talks an RPC server, etc. |
| |
| Args: |
| name: Name of the rule. |
| test: Label for the test to execute (can be any *_test target). |
| env: Label for the environment binary (can be any *_binary target). |
| timeout_secs: Approximate maximum number of seconds to wait for the environment to be ready. |
| """ |
| native.sh_test( |
| name = name, |
| srcs = ["//bazel/test_on_env:test_on_env.sh"], |
| args = [ |
| "--test-bin $(location %s)" % test, |
| "--env-bin $(location %s)" % env, |
| "--ready-check-timeout-secs %d" % timeout_secs, |
| ], |
| data = [test, env], |
| ) |