| 1 | # Testing and the Linux host |
| 2 | |
| 3 | The normal development loop is local: |
| 4 | |
| 5 | `` `sh |
| 6 | make verify |
| 7 | make test-race |
| 8 | `` ` |
| 9 | |
| 10 | `make verify` runs the Go tests, Go vet, JavaScript tests and a check that the bundled browser dependencies match their locked sources. Install JavaScript dependencies with `npm ci` first. `make web-test` runs the browser checks alone. |
| 11 | |
| 12 | The repository also contains a multistage Docker build. `make docker-test` runs `TEST_PACKAGES` (default `./...` ) under Go 1.27.1 on Debian Bookworm with the race detector. `make docker-build` builds the self-hosted runtime image. |
| 13 | |
| 14 | ## Component checks |
| 15 | |
| 16 | Build all executables with `make build` . Run the focused component suites with: |
| 17 | |
| 18 | `` `sh |
| 19 | go test -race ./protocol/... ./internal/auth ./internal/event ./tinygit ./cmd/tinygit ./tinyclient ./cmd/tinyclient |
| 20 | go test ./internal/daemon -run TestStandaloneTinyclient |
| 21 | npm run test:tinyclient |
| 22 | `` ` |
| 23 | |
| 24 | The tinygit command test exercises a real binary through signed metadata publication, Git push, clone, unauthorized-ref rejection and restart. The tinyclient integration test compares the standalone frontend with the integrated renderer using a real backend, including session authentication, signed writes, logout and private metadata masking. Public-consumer and dependency checks guard the package boundaries. |
| 25 | |
| 26 | Run `make verify` for the full integrated regression suite before shipping. Standalone tests verify the documented component profiles, not every integrated capability. During an extraction, also compare the baseline and refactored binaries using the same fixture data and check that moved browser assets and existing tests were retained. See the [module contracts](module-contracts.md#verification). |
| 27 | |
| 28 | ## Remote Linux host |
| 29 | |
| 30 | `scripts/test-linux.sh` runs the same internal race test in an isolated Docker build on the configured Linux host. It synchronizes the exact worktree, including untracked files, over SSH into a unique directory under `~/tinyrelay-tests/` in the remote home directory; it never runs global Docker cleanup and never edits host configuration. |
| 31 | |
| 32 | `` `sh |
| 33 | LINUX_HOST=<host> LINUX_NAME=tinyrelay-review-1 ./scripts/test-linux.sh |
| 34 | `` ` |
| 35 | |
| 36 | Useful overrides are `LINUX_PACKAGES` (the default internal package list) and `LINUX_ARTIFACTS` (local artifact destination). The script records UTC time, host, kernel, CPU count, Docker server version, Go version, target platform, and SQLite module version beside the Docker build log, including a status file when the build fails. A unique `LINUX_NAME` is required when multiple runs share a host. |
| 37 | |
| 38 | To run the complete tree on Linux, set `LINUX_PACKAGES='./...'` . |
| 39 | |
| 40 | The runtime image is a small Debian image containing the static Go binary, `ca-certificates` , and `git` . It runs as UID 10001 (`relay` ) with `/data` as the writable volume. Bind the relay and diagnostics listeners explicitly; diagnostics should stay on loopback or a protected Tailscale address and must not be published publicly. |
| 41 | |
| 42 | Performance runs should use a separate artifact name and record workload seed, client version, host CPU, Go version, SQLite version, storage medium, configuration, raw logs, and profiles. Capacity claims are meaningful only when those inputs are kept with the result. |
| 43 | |
| 44 | The checked-in benchmarks provide a repeatable first baseline without claiming an optimized capacity: |
| 45 | |
| 46 | `` `sh |
| 47 | make benchmark |
| 48 | LINUX_HOST=<host> ./scripts/bench-linux.sh |
| 49 | `` ` |
| 50 | |
| 51 | `BenchmarkSave` , `BenchmarkQuery` , and `BenchmarkTextSearch` use a local SQLite WAL store with representative seeded events. `BenchmarkFanout` measures only the in-memory broadcast and enqueue path to 10, 100, and 1,000 subscribed clients; it excludes websocket network writes and client-reader scheduling. The benchmark script records the Linux host, CPU count, Docker/Go/SQLite versions, benchmark output, and exit status under `artifacts/bench/` ; use `BENCH_PACKAGES` and `BENCHTIME` for controlled comparisons. Treat these as baselines until a workload and hardware matrix supports a capacity claim. |
| 52 | |
| 53 | For Git workloads that include child processes inside Docker, `scripts/observe-git-benchmark.py` captures the benchmark output, host load/memory, and Docker cgroup v2 CPU, memory, I/O, and PID samples every 500ms. It also snapshots authenticated `/metrics` , heap, and goroutine profiles before and after the run. The optional `--cpu-profile` captures one bounded 60-second Go CPU profile; cgroup samples remain the source for child CPU accounting. |
| 54 | |
| 55 | `` `sh |
| 56 | python3 scripts/observe-git-benchmark.py --out artifacts/git/baseline \ |
| 57 | --container tiny-git-perf-baseline \ |
| 58 | --diagnostics http://127.0.0.1:17448 --token "$TINY_DIAGNOSTICS_TOKEN" \ |
| 59 | -- ./scripts/git-performance.mjs |
| 60 | `` ` |
| 61 | |
| 62 | The [conformance suite](../scripts/conformance/README.md) runs black-box NIP and GRASP cases against a running local daemon and preserves stdout, stderr, status, and environment artifacts. Start the daemon, then run `node scripts/conformance/run.mjs` . To try the Bunker URL sign-in without a phone, run `node scripts/qa/nip46-bunker.mjs` and paste the printed URL into the sign-in page. |
| 63 | |
| 64 | The [UI checks](../scripts/qa/README.md) cover hosted viewers, malformed URLs, signer controls, browser history, failed requests and mobile navigation with and without JavaScript. |
| 65 | |
| 66 | ## Real Git repositories |
| 67 | |
| 68 | The Git performance harness below records raw profiles and results under `artifacts/git-performance/` . |
| 69 | |
| 70 | Prepare a new corpus from committed local branches and tags. This leaves the source repositories unchanged and refuses an existing output directory: |
| 71 | |
| 72 | `` `sh |
| 73 | python3 scripts/prepare-git-performance.py \ |
| 74 | --source-directory "$HOME/Developer" --out /tmp/tiny-git-corpus |
| 75 | `` ` |
| 76 | |
| 77 | Create a dedicated test tenant using the public benchmark fixture identity, then start a separate test daemon. Never use this identity for a real relay: |
| 78 | |
| 79 | `` `sh |
| 80 | tiny tenant create --data-dir /tmp/tiny-git-test --name main \ |
| 81 | --owner 5ac640e5df8f7945381c31f435288ba3f587fbd68efb27abaf941792f9c36369 |
| 82 | tiny serve --data-dir /tmp/tiny-git-test --default-tenant main \ |
| 83 | --listen 127.0.0.1:17447 --allow-private-relays |
| 84 | `` ` |
| 85 | |
| 86 | In another terminal, enable Git hosting and run the workload: |
| 87 | |
| 88 | `` `sh |
| 89 | node scripts/configure-git-performance.mjs http://127.0.0.1:17447 |
| 90 | node scripts/git-performance.mjs --relay ws://127.0.0.1:17447 \ |
| 91 | --repos-dir /tmp/tiny-git-corpus --out artifacts/git-performance/local-run \ |
| 92 | --repeats 3 |
| 93 | `` ` |
| 94 | |
| 95 | Use `--only strudel,atlas` to select fixtures. Each run creates distinct signed repository identities, checks all transferred refs and HEAD, runs `git fsck` , and measures relay EVENT/REQ traffic throughout the Git phases. The incremental push adds a commit with an unchanged tree; it is a small metadata update, not a new binary upload. |
| 96 | |
| 97 | Add `--private` to both commands to test a GRASP-08 private tenant. The private fixture uses the documented benchmark owner key, so it is already a tenant member. The harness authenticates its control WebSocket with the repository signer and starts a loopback signing proxy for native Git. The proxy adds a repository-root proof with the literal `GET` method to each Git request, and its temporary file handling is included in private timings. Signed repository state authorizes each pushed ref. Use a fresh data directory for each comparison. Do not interpret private timings as a like-for-like unauthenticated native Git comparison. |
| 98 | |
| 99 | For native Git comparisons, `go run ./scripts/git-http-baseline --root /path/to/fresh-bare-repos --listen 127.0.0.1:17449` exposes a benchmark-only HTTP server. Initialize one empty bare `<name>.git` per fixture, set its symbolic HEAD to the corpus manifest's `head_branch`, and enable `http.receivepack`. Add `--baseline http://127.0.0.1:17449` to the workload. Use fresh baseline repositories for each run so initial pushes transfer the complete corpus. |
| 100 | |
| 101 | The raw JSON records failures as failures; interrupted or absent phases are not successful samples. The observer separates Go process memory from container memory, which also includes native Git and file cache. Run performance measurements separately from compilation and test suites on the same host. |
| 102 | |
| 103 | ## Git collaboration checks |
| 104 | |
| 105 | Run `npm run test:collaboration` to check signed issue, reply, status and pull request events. Run `go test ./internal/daemon ./tinygit ./internal/replication ./tinyclient` for collaboration queries, access controls, synchronization, Git repair and page rendering. |
| 106 | |
| 107 | The UX fixture includes an issue, a threaded comment, a status change and a pull request with a real Git diff. Use a disposable daemon when testing signed browser publishing. |