三種服務管理方案

Process.start（直接啟動程序）

在 test 的 setUp 中用 Process.start 啟動服務程序，tearDown 中用 process.kill 停止。

適合的前提：服務是單一二進位檔（不需要 Docker），啟動速度快（< 2 秒），不需要持久化狀態。

app_tunnel 的 ttyd 就是這個模式。ttyd bash 一行指令啟動，不需要設定檔，不需要資料庫，啟動到可接受連線約 500ms。Test harness 只需要：

1setUp: process = Process.start('ttyd', ['--port', '7681', 'bash'])
2       await waitForPort(7681, timeout: 3s)
3tearDown: process.kill()

Docker Compose

用 Docker Compose 定義服務堆疊，CI 的 before_all 階段 docker compose up，after_all 階段 docker compose down。

適合的前提：服務有依賴（database + cache + app server）、需要特定 OS 環境、需要精確的版本控制。

Docker Compose 的成本是 image pull 時間（首次或 image 更新時）和容器啟動時間。CI 中可以用 image cache 減少 pull 時間，但冷啟動仍比直接啟動程序慢。

Testcontainers

在 test 程式碼中用 testcontainers 套件管理 Docker 容器。每個 test class 或 test suite 啟動自己的容器，test 結束後自動清理。

適合的前提：和 Docker Compose 類似，但需要更細粒度的控制（不同 test 用不同的服務設定），或需要在 test 程式碼中動態決定服務的啟動參數。

Testcontainers 的優勢是 test 和 fixture 在同一個程式碼檔案中，容易理解每個 test 需要什麼環境。缺點是每個 test suite 啟動自己的容器，比共用容器慢。

健康檢查

服務啟動後到可以接受請求之間有延遲。直接在啟動後發送 test request 會因為服務尚未 ready 而失敗。

健康檢查的方式依服務類型而定：

TCP port 可達：waitForPort(port, timeout) 反覆嘗試 TCP 連線，成功即表示服務在監聽。最簡單，適合所有 TCP 服務。

HTTP health endpoint：對 /health 或 /ready 發送 GET request，收到 200 表示服務 ready。比 port check 更可靠 — port 監聽不代表應用層 ready。

特定操作成功：執行一個輕量的業務操作（例如 WebSocket 連線 + 簡單指令），成功表示服務完全 ready。最可靠但最慢。

服務狀態隔離

不同 test 之間的服務狀態需要隔離 — test A 在服務中建立的資料不應該影響 test B。

三種隔離策略：

每 test 重啟服務：最強隔離，最慢。適合服務啟動快（< 1 秒）的場景。

每 test 重設狀態：服務持續運行，test 開始前清理狀態（truncate tables, flush cache）。適合服務啟動慢但重設快的場景。

每 test 用獨立 namespace：服務持續運行，每個 test 使用獨立的 database schema / topic / channel。適合支援多租戶的服務。

app_tunnel 的 ttyd 是無狀態服務（每次連線是獨立的 terminal session），不需要狀態隔離。每個 test 建立新的 WebSocket 連線 = 新的 session。

下一步路由

• 什麼時候值得建 protocol integration test 基礎設施 → 成本判斷表
• Protocol integration test 的定義 → Protocol integration test 定義
• WebSocket 的 protocol test 實作 → WebSocket 協議測試實作

本文的驗收標準是：你能建立 v1 fixture、套用 v2 migration、產生 v2 snapshot，並用 validation query 證明資料合約仍成立。

Create Fixture

Create fixture 的核心責任是建立乾淨、可重建的 source fixture。沿用 quickstart schema，或重新建立一份 fixture DB。

 1mkdir -p /tmp/sqlite-fixture-lab
 2cd /tmp/sqlite-fixture-lab
 3rm -f fixture-v1.db fixture-v2.db
 4sqlite3 fixture-v1.db <<'SQL'
 5PRAGMA foreign_keys = ON;
 6PRAGMA user_version = 1;
 7
 8CREATE TABLE accounts (
 9  id INTEGER PRIMARY KEY,
10  owner_name TEXT NOT NULL,
11  status TEXT NOT NULL CHECK (status IN ('active', 'closed')),
12  created_at TEXT NOT NULL
13) STRICT;
14
15CREATE TABLE ledger_entries (
16  id INTEGER PRIMARY KEY,
17  account_id INTEGER NOT NULL REFERENCES accounts(id),
18  amount_cents INTEGER NOT NULL CHECK (amount_cents != 0),
19  idempotency_key TEXT NOT NULL UNIQUE,
20  created_at TEXT NOT NULL
21) STRICT;
22
23INSERT INTO accounts VALUES (1, 'Ada', 'active', '2026-05-21T00:00:00Z');
24INSERT INTO ledger_entries(account_id, amount_cents, idempotency_key, created_at)
25VALUES (1, 1000, 'fixture-v1-ada', '2026-05-21T00:10:00Z');
26SQL

這個 fixture 是 v1 source of truth。CI 可以每次從 SQL 重建，也可以保存 fixture-v1.db 作為 binary fixture；兩者都要有版本與 checksum。

Pre-Migration Snapshot

Pre-migration snapshot 的核心責任是建立 rollback 起點。正式 migration 前應先保存 source DB。

1sqlite3 fixture-v1.db ".backup 'fixture-v1-before-migration.db'"
2sqlite3 fixture-v1-before-migration.db "PRAGMA integrity_check;"

這份 snapshot 代表 migration 失敗時的回退點。CI log 要保留 snapshot path、schema version 與 migration id。

Apply Add Column Migration

Apply add column migration 的核心責任是展示低風險 schema change。先複製 v1，再套用 v2。

1cp fixture-v1.db fixture-v2.db
2sqlite3 fixture-v2.db <<'SQL'
3PRAGMA foreign_keys = ON;
4BEGIN;
5ALTER TABLE accounts ADD COLUMN email TEXT;
6PRAGMA user_version = 2;
7COMMIT;
8SQL

驗證 schema version 與新欄位：

1sqlite3 fixture-v2.db <<'SQL'
2PRAGMA user_version;
3PRAGMA table_info(accounts);
4SQL

Add column 是較簡單的 migration。涉及 drop column、rename、constraint 重建或資料 reshape 時，應改用 table rebuild 策略。

Table Rebuild Example

Table rebuild 的核心責任是展示 SQLite schema migration 的高風險路徑。以下範例把 accounts.status 的 allowed value 加入 suspended，透過新表重建 constraint。

 1sqlite3 fixture-v2.db <<'SQL'
 2PRAGMA foreign_keys = OFF;
 3BEGIN;
 4
 5CREATE TABLE accounts_new (
 6  id INTEGER PRIMARY KEY,
 7  owner_name TEXT NOT NULL,
 8  status TEXT NOT NULL CHECK (status IN ('active', 'closed', 'suspended')),
 9  created_at TEXT NOT NULL,
10  email TEXT
11) STRICT;
12
13INSERT INTO accounts_new(id, owner_name, status, created_at, email)
14SELECT id, owner_name, status, created_at, email
15FROM accounts;
16
17DROP TABLE accounts;
18ALTER TABLE accounts_new RENAME TO accounts;
19
20PRAGMA user_version = 3;
21COMMIT;
22PRAGMA foreign_keys = ON;
23SQL

Table rebuild 要保存 index、trigger、view 與 FK reference。這個 lab 只有小型 schema；正式 migration 要先列出所有 dependent object。

Validation Query

Validation query 的核心責任是證明 migration 後資料仍符合 domain invariant。

1sqlite3 fixture-v2.db <<'SQL'
2PRAGMA integrity_check;
3PRAGMA foreign_key_check;
4SELECT COUNT(*) AS account_count FROM accounts;
5SELECT COUNT(*) AS ledger_count FROM ledger_entries;
6SELECT SUM(amount_cents) AS total_balance FROM ledger_entries;
7PRAGMA user_version;
8SQL

驗收結果應包含 integrity ok、foreign key check 空結果、account count 1、ledger count 1、total balance 1000、user version 3。

Contract Test Hook

Contract test hook 的核心責任是讓 fixture 進入 CI。語言與 framework 可以不同，但測試要固定做三件事：開啟 FK、確認 schema version、跑 repository contract。

1test setup:
2  copy fixture-v2.db to temp path
3  open SQLite connection
4  execute PRAGMA foreign_keys = ON
5  assert PRAGMA user_version = 3
6  run repository contract tests

每個 test 使用 temp copy 可以避免資料污染。需要測 concurrency 時，改用 WAL busy reproduction。

Rollback Note

Rollback note 的核心責任是把 migration 失敗時的處理寫清楚。這個 lab 的 rollback 是保留 fixture-v1-before-migration.db，在 migration validation 失敗時停止 release 並保存 failed DB。

正式 runbook 要記錄：

1. Migration id 與 source / target user_version。
2. Pre-migration backup path。
3. Validation query 與結果。
4. Failed DB 保存路徑。
5. Release block / rollback 條件。

完成本篇後，下一步可以讀 SQLite to PostgreSQL migration 或 SQLite to D1 / Turso migration。

本文是 SQLite overview 的 implementation-layer deep article。Overview 已說明 SQLite 適合作為 test fixture；本文聚焦 如何用 SQLite 加速測試，同時保留 production database 的語意邊界。

SQLite test fixture 的核心責任是讓 repository / adapter 測試快速、可重複、可攜帶。SQLite 的單檔特性讓 CI 可以快速建立 DB、載入 seed、跑 contract test；但它的 type affinity、SQL dialect、locking 與 constraint behavior 和 PostgreSQL / MySQL 不完全相同，因此 fixture 要被定位為一層測試工具，而非 production equivalence。

本文的判讀錨點是：SQLite fixture 適合驗證 application contract，不適合取代 production database compatibility test。若測試目標是 repository error mapping、domain invariant、migration fixture 或 deterministic seed，SQLite 很划算；若測試目標是 PostgreSQL extension、MySQL lock、query planner 或 SQL dialect，應使用 production-like container。

Test fixture 的位置

SQLite fixture 的服務責任是提供快、穩定、可重建的本地資料狀態。它通常位於 unit test 與 full integration test 之間，承擔 repository adapter 的 contract test。

這張表的重點是把測試目的說清楚。SQLite fixture 讓語言教材與 backend 教材接起來；語言端測 interface / adapter，backend 端保留 production database 的深度文章與 migration playbook。

Fixture lifecycle

Fixture lifecycle 的核心責任是讓每次測試拿到已知資料狀態。常見策略有三種：每 test 建新 in-memory DB、每 suite 複製 template file、每 CI job 產生 versioned fixture。

Fixture file 應和 schema version 綁定。檔名、metadata 或 user_version 要能回答「這個 fixture 對應哪個 migration 版本」，避免測試資料在多次 schema 變更後變成隱性技術債。

Production dialect gap

Production dialect gap 的核心責任是避免 SQLite 測試通過後，PostgreSQL / MySQL production 出現不同語意。SQLite 的 dynamic typing、date / time representation、foreign key pragma、ALTER TABLE 支援與 lock model 都會影響測試可信度。

這張表的用法是決定哪些測試留在 SQLite，哪些要升級到 production-like DB。Repository contract 可用 SQLite；query optimization、vendor SQL、online schema change、CDC、replication、pooling 都應回到 PostgreSQL / MySQL 章節。

Contract test 設計

Contract test 的核心責任是讓不同 DB adapter 對 application 呈現同一組語意。SQLite fixture 測的是 application port 的行為，例如 duplicate key、not found、transaction rollback、pagination、domain invariant，而非底層 engine 的所有細節。

1Repository contract
2├── Create / read / update / delete
3├── Unique conflict → ErrAlreadyExists
4├── Missing row → ErrNotFound
5├── Transaction rollback restores domain invariant
6├── Pagination order stable
7└── Migration version matches fixture

如果 production adapter 是 PostgreSQL / MySQL，contract test 應至少在 nightly 或 CI matrix 裡跑一輪 production-like database。SQLite 提供快速回饋，production-like test 提供 dialect confidence。

CI evidence

SQLite fixture 的 CI evidence 要證明資料狀態和 schema version 一致。測試失敗時，讀者要能知道是 application contract 失效、fixture 過期、migration 漏跑，還是 SQLite / production dialect gap。

CI 產物不一定要很複雜，但要能被下一個維護者重建。SQLite fixture 的優勢是可攜帶；若 fixture 只能靠某個人的本機狀態生成，就失去教學與維護價值。

Production 踩雷

Case 1：共用同一個 .db 檔跑平行測試

平行測試共用檔案的核心風險是 test runner 製造和 production 不同的 writer collision。測試偶發 SQLITE_BUSY，團隊可能以為 application 有 race；實際上是測試隔離不足。

修正方向是 per-test temp DB 或 read-only template copy。需要測 WAL / busy 行為時，用專門 hands-on lab，讓一般 contract test 專注在 repository contract。

Case 2：忘記開 foreign keys

Foreign key pragma 漏開的核心風險是 constraint bug 被 fixture 隱藏。SQLite foreign key enforcement 需要明確啟用；若 production DB 一定 enforce FK，fixture 也要在 connection initialization 中開啟。

修正方向是 baseline PRAGMA 和 startup assertion。每個 test DB open 後都跑 PRAGMA foreign_keys 並驗證結果。

Case 3：SQLite fixture 掩蓋 vendor-specific SQL

Vendor-specific SQL 被 SQLite 掩蓋的核心風險是 query 到 production 才失敗。例如 PostgreSQL JSONB、partial index、full-text search 或 MySQL generated column、optimizer hint 都應在 vendor DB 測。

修正方向是把 SQL 分層。Portable repository contract 可以用 SQLite；vendor-specific query 要有 PostgreSQL / MySQL test container。

操作檢查清單

SQLite fixture 設計前要回答：

1. 這個測試驗證 application contract 還是 production dialect。
2. Fixture 是 in-memory、template copy、generated file 還是 read-only。
3. PRAGMA foreign_keys、journal_mode、busy_timeout 是否固定。
4. Fixture version 如何對齊 migration version。
5. Parallel test 是否每個 worker 有獨立 DB file。
6. 哪些 query 必須在 PostgreSQL / MySQL container 再跑。
7. CI artifact 是否保留 migration log 與 dialect gap note。

下一步路由

• 上游：Repository Adapter
• Sibling：Schema Migration / Versioning、SQL Dialect and Index Limits
• 操作：Migration Fixture Lab
• 平行：PostgreSQL、MySQL
• 官方：SQLite Datatypes、SQLite STRICT Tables、SQLite PRAGMA