Skip to content

Client/server mode

Tryke can run as a persistent server that keeps Python workers warm between file changes and caches test discovery. Clients connect over TCP to request test runs with minimal startup overhead.

Starting the server

tryke server

The server listens on 127.0.0.1:2337 by default. Change the port with --port:

tryke server --port 9000

On startup, the server:

  1. Spawns and pre-warms the worker pool
  2. Runs initial test discovery
  3. Starts watching the filesystem for changes

Running tests against the server

Use --port on tryke test to connect to a running server instead of spawning fresh workers:

tryke test --port
tryke test --port 2337

All standard flags work: -k, -m, path arguments, -x, --maxfail. Filtering happens server-side.

tryke test --port -k "math" -x

Protocol

The server uses JSON-RPC 2.0 over TCP with newline-delimited messages.

Request/response

{"jsonrpc": "2.0", "id": 1, "method": "ping"}
{"jsonrpc": "2.0", "id": 1, "result": "pong"}

Available methods

Method Description
ping Liveness check, returns "pong"
discover Re-scan for tests, returns the test list
run Execute tests with optional filters, streams results

Streaming notifications

During a test run, the server broadcasts notifications (no id field) to all connected clients:

{"jsonrpc": "2.0", "method": "run_start", "params": {"tests": [...]}}
{"jsonrpc": "2.0", "method": "test_complete", "params": {"result": {...}}}
{"jsonrpc": "2.0", "method": "run_complete", "params": {"summary": {...}}}

File changes trigger a discover_complete notification with the updated test list.

Filesystem watching

The server watches all .py files in the project (respecting .gitignore) with a 50ms debounce. When files change:

  1. The batch is dedup'd against each path's last-seen (mtime, size) so editor tail events that don't actually change the file (metadata fsync, swap-file cleanup, format-on-save with identical output) are dropped before any work happens
  2. The import graph is incrementally updated
  3. The worker subprocesses are restarted so the next run loads fresh code in a brand-new Python interpreter (no importlib.reload)
  4. A discover_complete notification is broadcast to all connected clients

This means editors can keep their test explorer up to date in real time without spurious double-restarts on a single save.

Editor integration

Server mode is designed for editor plugins. Two official integrations exist:

A typical workflow:

  1. Start the server in a terminal: tryke server
  2. The editor plugin connects and sends a discover request to populate the test explorer
  3. When you run a test, the plugin sends a run request
  4. Results stream back as test_complete notifications for real-time progress
  5. File changes automatically update the test list via discover_complete

See the editor integration guide for setup instructions.

Why server mode

Without the server, every tryke test invocation pays for Python startup and test discovery. With the server:

  • Worker processes stay warm between file changes — no Python startup per run; on a file change, workers are restarted and immediately re-warmed in parallel so the next run is still on warm interpreters
  • Discovery is cached — only changed files are re-scanned
  • Multiple clients — several editor windows or terminals can share one server