gemstone-nexus · Phase 6
DOC14 — Unit Test Results
Metadata
| id | doc_id | title | category | source_path | summary | content_hash | indexed_at |
|---|---|---|---|---|---|---|---|
| 32 | DOC14 | DOC14 — Unit Test Results | doc_suite | DevResources/docs/DOC14-Unit-Test-Results.md | GemStone implements a three-tier testing architecture plus a UAT framework. All runs are logged to a dated narrative file and the Project Ledger database. make test executes all tiers in sequence. | 15aaaee843054f450564c886b53510f6a17c5cb9 | 2026-07-22 18:33:18 |
Content
# DOC14 — Unit Test Results
*Testing architecture, coverage targets, and representative test cases. Dated pass/fail narratives are appended to this document and the Project Ledger as phases close; until then this DOC is the coverage contract, not a completed results log.*
**Initiative:** GemStone · **Version:** v2.0 (Rewrite) · **Status:** Approved for Build · **Date:** July 17, 2026
## 1. Testing Architecture Overview
GemStone implements a three-tier testing architecture plus a UAT framework. All runs are logged to a dated narrative file and the Project Ledger database. make test executes all tiers in sequence.
## 2. Test Tiers
| Tier | Framework | Runs In | Scope |
| --- | --- | --- | --- |
| Unit (backend) | Pytest | gemstone-api container | Service functions, 100% function coverage required |
| Unit (frontend) | Vitest + RTL | gemstone-mobile container | React components, 80%+ line coverage required (API clients 90%+; see Section 4) |
| Integration | Pytest + test DB | gemstone-api + test postgres | API/DB flows, org_id scoping, tier enforcement |
| E2E | Playwright + Chromium | playwright container | Full stack via NGINX, critical user flows |
| UAT Structured | Custom script runner | gemstone-api | Predefined flow scripts, pass/fail per step |
| UAT Behavioral | Event instrumentation | gemstone-mobile (continuous) | All primary user actions, logged to Ledger |
## 3. Representative Test Cases
```
def test_tier_immutable_after_creation():
session = create_session(tier=SecurityTier.STANDARD)
with pytest.raises(IntegrityError):
db.execute(update(Session).where(Session.id == session.id).values(tier="open_mode"))
def test_didymus_task_cannot_reach_running_without_approval():
task = submit_task(requested_by="Cursor", target_worker="cursor")
assert task.status == "PENDING"
with pytest.raises(IntegrityError):
db.execute(update(DidymusTask).where(DidymusTask.id == task.id).values(status="RUNNING"))
def test_notebook_link_does_not_remove_from_recents():
session = create_session(...)
link_to_notebook(session.id, notebook_id)
recents = get_recents(practitioner_id)
assert session.id in [s.id for s in recents]
def test_cross_org_isolation_under_concurrency():
sessions_a = [create_session(org_id=ORG_A) for _ in range(25)]
sessions_b = [create_session(org_id=ORG_B) for _ in range(25)]
# assert no query path for org A ever returns org B data
async def test_tts_first_chunk_latency():
start = time.monotonic()
first_chunk = await anext(tts_provider.stream_synthesize("Hello there."))
assert (time.monotonic() - start) < 0.8
```
## 4. Coverage Requirements
| Layer | Coverage Target | Enforcement |
| --- | --- | --- |
| Python API (services) | 100% function coverage | Merge to main blocked if untested |
| Python API (routers) | 90%+ line coverage | Happy-path and primary error cases |
| TypeScript (components) | 80%+ line coverage | User interactions and state changes |
| TypeScript (API clients) | 90%+ line coverage | Mock responses, all error states |
| Integration (API + DB) | Key flows only | Voice session, Atlas context, tier enforcement, Didymus gate, org_id scoping |
| E2E (Playwright) | Critical flows | Voice round-trip, pack install, Notebook/Recents, task approval, Field Mode |
## 5. Phase 5 status (2026-07-21)
| Item | Status |
| --- | --- |
| Playwright critical-path suite (`frontend/e2e/`) | **PASS** 2026-07-21: `npm run test:e2e:twice` → 9/9 then 9/9 |
| Device / sunlight / wake UAT (DOC20) | Practitioner — not claimed by Playwright |
| Unit/integration coverage targets (Section 4) | Standing contract; not re-measured this Phase 5 engineering pass |
See `DevResources/docs/DOC-Phase5-Hardening-Scaffold.md` for the Phase 5 engineering vs practitioner matrix.
---
NEXTECH Business Technology Management LLC · nex-tech.biz · (941) 499-5505