# Integration tests

These tests spin up a real `chain serve` subprocess against a
fresh temp dir and exercise Studio's Hub-facing data layer
against it. They cover the "kind of regression that survives
unit tests because the system-shape only manifests across the
gRPC boundary".

## Status

**Scaffold.** One canonical test (capabilities). The harness is
production-quality (proper teardown, idempotent, port-clean) so
new tests slot in by importing `hub_fixture.dart` and calling
`HubFixture.start()` / `dispose()` in `setUp` / `tearDown`.

What's NOT here yet:

- A full "install dep → run echo → assert title" scenario. The
  harness can do it (install_module is a real RPC), but
  building the fixture for module-bundle downloads against a
  hermetic local registry is its own scaffold. Tracked as
  follow-up to S-21.
- Studio-side widget testing against the live hub. The
  flutter `integration_test` package supports it
  (`testWidgets` + `IntegrationTestWidgetsFlutterBinding`),
  but pumping a full `StudioApp` against a real gRPC channel
  needs `binding.enableSurfaceBindingHack()` ceremony we
  haven't designed yet.

## Running

```bash
cd chain_studio
flutter test test/integration/
```

Prereq: a `fai` binary on PATH or at
`../fai_chain/target/release/chain`. The harness skips with a
clear message when neither exists, so this command does not
fail on a fresh checkout — it just reports skipped tests.

To get the binary:

```bash
cd ../fai_chain
cargo build --release --bin fai
```

### First-time-start gotcha

A cold `chain serve` spends its first ~30s building the
curated-model database and initialising SQLite migrations.
`HubFixture.start()` waits up to 60s by default; if your local
hub takes longer the first time, run `chain serve` once by hand
against any temp `CHAIN_DATA_DIR` to warm the per-user cargo /
SBOM caches:

```bash
CHAIN_DATA_DIR=/tmp/chain_warmup chain serve --bind 127.0.0.1:0
# wait for "hub started", Ctrl-C
```

Subsequent integration-test runs are quick.

## Not yet wired into CI

`.forgejo/workflows/ci.yml` doesn't run these yet. Adding them
needs an artifact-passing pattern: the platform build job
publishes `target/release/chain` as a CI artifact; the studio
test job consumes it. Pattern is straightforward once we want
it; it's deferred because we don't yet have enough integration
tests to justify the CI runtime.