From 50f4c0bfdbcc5d6e24a1f7e0c7201e2651320488 Mon Sep 17 00:00:00 2001 From: Zeshi Du Date: Mon, 19 Oct 2026 14:09:46 -0700 Subject: [PATCH] docs(readme): shorten the local-testing tunnel notes The paragraph after the local-testing example had grown into a wall of transport and retry internals. Keep what a first-time reader needs (what --local saves, picking a host, slow dev servers, TLS behind a re-signing proxy, the 60-second connect limit, cancellation and refunds, plan authoring, Portal runs) and leave the rest to DOCUMENTATION.md, which already covers it. --- README.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index e9e1134..ce69eb9 100644 --- a/README.md +++ b/README.md @@ -154,11 +154,11 @@ Hit the tunnel limit? Run `testsprite tunnel list`, then `testsprite tunnel stop A second `tunnel start` or process using the same credential takes over, and the first exits **10**. An environment is one origin (scheme, host and port) plus its sign-in configuration. Frontend runs automatically open a tunnel for a saved `localhost`, `127.0.0.1` or `[::1]` URL: `test run`, `test rerun`, `test create --run`, `test create-batch --run` and `testlist run` use this behavior. `--env ` selects the environment; omit it for the project default. `--no-wait` disables automatic tunnels; drop it to run through one. If environment reads are unavailable, the command keeps the previous server behavior. Several fresh-run IDs require a tunnel; public targets retain the exit-5 refusal. A named public environment used against a local origin prints a sign-in advisory on stderr. Reruns and test-list runs share one timeout including capacity waits and require the server to confirm tunnel support; an older server triggers a cancellation attempt and a clear error. -`--local ` remains a shorthand and defaults new project/environment URLs to `http://localhost:`. On a test run it preserves the host of a selected loopback environment, or the one host agreed by saved non-temporary loopback environments on that port; otherwise it uses `localhost`. If environment reads fail, it retains the legacy `127.0.0.1` host. Saved URLs retain their exact spelling, and aliases are not merged. `--local-host` remains accepted but is deprecated and hidden from project/environment help; prefer `--url http://127.0.0.1:` or `--url http://[::1]:` when the host matters. Dev servers can take a minute per page through a tunnel; test a built server with `npm run build` and your framework's preview/start command for heavy apps. -The control plane is WebSocket over TLS (`wss://control.tun.testsprite.com/ws`). The data plane, which carries the tunnel secret and proxied traffic, uses TLS at `data.tun.testsprite.com:443` and verifies the certificate with Node's default trust store: its bundled Mozilla roots, plus certificates supplied through `NODE_EXTRA_CA_CERTS` and the system CAs when Node is started with `--use-system-ca`. Node 20 is supported without losing `NODE_EXTRA_CA_CERTS`. Verification cannot be disabled, and the CLI never falls back from TLS to plaintext. On a network that re-signs TLS, export your organisation's root CA to a PEM file and set `NODE_EXTRA_CA_CERTS=/path/to/ca.pem` before running `testsprite`. Plaintext connects and TLS handshakes each time out after 10 seconds. The first failed attempt starts a **60-second** retry episode; writing `TunnelHello` is not enough to reset it. The episode ends only after the first inbound tunnel stream or after the socket remains open for 5 seconds following the hello. A real deadline timer stays armed across retries and destroys an in-flight socket when it expires. After that, an owned `test run --local` run is cancelled and refunded and the command exits **10**; `tunnel start` exits **10**. If a self-hosted or older TestSprite server does not advertise a TLS endpoint, the CLI prints a one-time warning and uses legacy plaintext port **7400** under the same timeout and retry rules. `tunnel start` prints `transport: tls` or `transport: plaintext`. -An owned tunnel's timeout or Ctrl-C cancels unfinished runs by default. A borrowed run still detaches without cancellation on Ctrl-C/SIGTERM because its owner keeps the tunnel alive; if that owner disappears while a run is active, the borrower cancels its own run and reports `cancelled`, `already finished`, or `skipped`. A run cancelled before it finishes is refunded. `--no-cancel-on-interrupt` also skips this owner-gone cancellation. Keep the early stderr run-id receipts (`Run ` for one test, `[i/N] → run ` for a batch) and read the reported runs before re-running. -Local projects skip exploration/plan generation; author plans with `test create --plan-from`. Portal runs are blocked for free until you set a public project URL. -See [the full local-testing reference](./DOCUMENTATION.md#local-frontend-testing-and-tunnels) for flags, login, billing/refunds, timeouts, and retargeting. +`--local ` saves new project and environment URLs as `http://localhost:`. Use `--url http://127.0.0.1:` or `--url http://[::1]:` when the host matters (`--local-host` is deprecated). Dev servers can be slow through a tunnel, so for heavy apps test a production build (`npm run build` plus your framework's preview or start command). + +The tunnel uses verified TLS. On a network that re-signs TLS, set `NODE_EXTRA_CA_CERTS=/path/to/ca.pem` to your organisation's root CA. If the tunnel keeps failing to connect for 60 seconds, the command exits **10**, and an owned run is cancelled and refunded. + +On an owned tunnel, Ctrl-C or a timeout cancels unfinished runs by default, and a run cancelled before it finishes is refunded. A run on a borrowed `--tunnel-client` detaches on Ctrl-C instead. Local projects skip plan generation, so write plans with `test create --plan-from`. Portal runs stay blocked, at no charge, until the project has a public URL. See [the local-testing reference](./DOCUMENTATION.md#local-frontend-testing-and-tunnels) for the details. ## Commands