stemedb/uat/consumer-health/QUICKSTART.md

UAT Quick Start Guide

Get Week 4 UAT scenarios running in 5 minutes.

Prerequisites

# 1. Ensure you're in the stemedb repo
cd /Users/jordanwashburn/Workspace/orchard9/stemedb

# 2. Build everything (one-time setup)
cargo build --workspace

Step-by-Step Execution

1. Start the API Server (Terminal 1)

cargo run -p stemedb-api

Wait for output like:

INFO  stemedb_api] Server running on http://0.0.0.0:18180

2. Validate API Readiness (Terminal 2)

cd uat/consumer-health
./validate_api_readiness.sh http://localhost:18180

Expected output:

✅ API is READY for UAT execution

3. Run UAT Tests

Option A: All scenarios at once

STEMEDB_API_URL=http://localhost:18180 \
cargo test --test consumer_health_uat run_all_uat_scenarios -- --ignored --nocapture

Option B: Individual scenarios

# GLP-1 Muscle Loss Contradiction
STEMEDB_API_URL=http://localhost:18180 \
cargo test --test consumer_health_uat uat_glp1_muscle_loss_contradiction -- --ignored --nocapture

# Gastroparesis Multi-Source
STEMEDB_API_URL=http://localhost:18180 \
cargo test --test consumer_health_uat uat_gastroparesis_multi_source -- --ignored --nocapture

# Layered Consensus
STEMEDB_API_URL=http://localhost:18180 \
cargo test --test consumer_health_uat uat_layered_consensus -- --ignored --nocapture

What You Should See

Successful Test Output

=== UAT: GLP-1 Muscle Loss Contradiction ===
Step 1: Ingest Study A (muscle loss observed)
  ✓ Study A hash: abcd1234...
Step 2: Ingest Study B (muscle mass preserved)
  ✓ Study B hash: ef567890...
Step 3: Query Skeptic Lens
  Status: Contested
  Conflict Score: 0.88
  Claims: 2
  Candidates: 2
✓ PASS: GLP-1 Muscle Loss Contradiction

Failed Test (Common Issues)

Issue 1: Connection refused

API error 000: Connection refused

Fix: Make sure API server is running in Terminal 1.

Issue 2: 404 Not Found

API error 404: No assertions found

Fix: This is normal if database is empty. Tests create data first.

Issue 3: 400 Bad Request - Invalid signature

API error 400: At least one signature is required

Fix: Signature validation is enforced. See "Known Issues" below.

Known Issues

Signature Validation

If tests fail with signature errors:

1. Check if API has test mode (recommended)
2. OR generate real signatures (complex, not recommended for UAT)

Database State

Tests write to a persistent database. To start fresh:

# Stop API server (Ctrl+C in Terminal 1)
# Remove database
rm -rf /tmp/stemedb-data  # or wherever your DB is
# Restart API server
cargo run -p stemedb-api

Next Steps After Successful Run

1. Capture Results

   • Take screenshots of test output
   • Copy actual values into UAT markdown files
   • Update test matrices

2. Sign Off

   • Mark scenarios as PASS in markdown files
   • Update crates/stemedb-ontology/ROADMAP.md
   • Commit results

3. Report Issues

   • Create GitHub issues for any failing tests
   • Document unexpected behavior
   • Propose fixes

Advanced Usage

Run with different API URL

STEMEDB_API_URL=http://staging.example.com:18180 \
cargo test --test consumer_health_uat -- --ignored --nocapture

Run specific test multiple times

for i in {1..5}; do
  echo "=== Run $i ==="
  STEMEDB_API_URL=http://localhost:18180 \
  cargo test --test consumer_health_uat uat_glp1_muscle_loss_contradiction -- --ignored --nocapture
done

Save test output to file

STEMEDB_API_URL=http://localhost:18180 \
cargo test --test consumer_health_uat run_all_uat_scenarios -- --ignored --nocapture \
2>&1 | tee uat_results_$(date +%Y%m%d_%H%M%S).log

Troubleshooting

"cargo: command not found"

Install Rust: https://rustup.rs/

"package stemedb-api not found"

cargo build --workspace

"Permission denied" for validate script

chmod +x uat/consumer-health/validate_api_readiness.sh

Tests are slow / timing out

Increase sleep durations in test code:

std::thread::sleep(std::time::Duration::from_secs(5));  // was 2

Documentation Links

• Full Execution Plan - Detailed instructions
• Delivery Summary - What was built
• UAT Scenarios - All 12 scenarios
• API Documentation - While server is running

Getting Help

Check logs:

• API server logs in Terminal 1
• Test output in Terminal 2

Common commands:

# Check if API is running
curl http://localhost:18180/v1/health

# View OpenAPI spec
curl http://localhost:18180/api-docs/openapi.json | jq .

# Check database location
# (Look for STEMEDB_DATA_DIR in API server logs)

---

Quick Reference Card

┌─────────────────────────────────────────────────────────────┐
│ Terminal 1: cargo run -p stemedb-api                        │
│ Terminal 2: ./validate_api_readiness.sh http://localhost... │
│ Terminal 2: STEMEDB_API_URL=... cargo test --test ...       │
└─────────────────────────────────────────────────────────────┘