remote-tests

Source excerpt starting at line 1.

1---2name: remote-tests3description: Testing against remote executors in integration tests.4---5 6Remote executor tests exercise the app-server/exec-server split to ensure that agent features work7in both local and remote execution environments.8 9Remote executor tests currently require an x86_64 Linux host machine. There are two flavors:10 111. Docker (Linux exec-server)122. Wine (Windows exec-server)13 14## Test Fixtures15 16Individual test cases must opt-in to being run against a remote executor.17 18### codex_core19 20Use `TestCodexBuilder::build_with_auto_env()` to opt-in to remote execution in core integration21tests unless the test needs more precise control over its executor.22 23### app-server24 25Start the server with `TestAppServer::new_with_auto_env()` unless the test defines its own26`$CODEX_HOME/environments.toml` or will define custom environments at runtime.27 28Start threads with `TestAppServer::send_thread_start_request_with_auto_env()` if you've created the29server with the `auto_env` approach. Omit `ThreadStartParams.environments` (leave it as `None`) when30doing so.31 32## Test Skips33 34If a test doesn't pass in a particular remote executor configuration you can skip it in just that35configuration. Include a string reason for future readers when the selected skip macro supports36one.37 38Choose the skip macro by what causes the test to fail:39 40- `skip_if_target_windows!`: Windows target behavior.41- `skip_if_wine_exec!`: Wine-exec runner constraints.42- `skip_if_host_windows!`: Windows host constraints.43- `skip_if_remote!`: Local-only test behavior.44- `skip_if_no_remote_env!`: Remote-only test behavior.45 46Prefer defining tests that run in all host/target configurations by default. See the `$path-types`47skill for the most common changes required to make tests compatible.48 49## Docker50 51Docker container is built and initialized via ./scripts/test-remote-env.sh. Sourcing this script52in bash also provides the `codex_remote_env_cleanup` function to use after testing.53 54To run core integration tests against a Docker remote executor:55 56```bash57bash -c '58  set -euo pipefail59  unset CODEX_TEST_REMOTE_EXEC_SERVER_URL60  source scripts/test-remote-env.sh61  trap codex_remote_env_cleanup EXIT62 63  cd codex-rs64  just test -p codex-core --test all65'66```67 68To run app-server integration tests against a Docker remote executor:69 70```bash71bash -c '72  set -euo pipefail73  unset CODEX_TEST_REMOTE_EXEC_SERVER_URL74  source scripts/test-remote-env.sh75  trap codex_remote_env_cleanup EXIT76 77  cd codex-rs78  just test -p codex-app-server --test all79'80```81 82## Wine83 84These tests build an exec-server for Windows and run it under Wine, with the app-server staying on85the Linux host. The cross-platform build dependency means they only run in Bazel.86 87For core integration tests:88 89```sh90bazel test //codex-rs/core:core-all-wine-exec-test91```92 93For app-server integration tests:94 95```sh96bazel test //codex-rs/app-server:app-server-all-wine-exec-test97```98 99## Devboxes100 101You can use a devbox to run these tests if you are running on a macOS machine.102 103You can list devboxes via `applied_devbox ls`, pick the one with `codex` in the name.104Connect to devbox via `ssh <devbox_name>`.105Reuse the same checkout of codex in `~/code/codex`. Reset files if needed. Multiple checkouts take longer to build and take up more space.106Check whether the SHA and modified files are in sync between remote and local.107