gemstone-nexus · Phase 6

DOC14 — Unit Test Results

← Documents

Metadata

iddoc_idtitlecategorysource_pathsummarycontent_hashindexed_at
32DOC14DOC14 — Unit Test Resultsdoc_suiteDevResources/docs/DOC14-Unit-Test-Results.mdGemStone 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.15aaaee843054f450564c886b53510f6a17c5cb92026-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