Smoke Test Suite - Complete Documentation Index

Created: 2026-05-29 | Status: ✅ Complete | Total Documentation: 1,778 lines

📋 Core Documents

1. SMOKE_TEST_CHECKLIST.md — Main Testing Guide

367 lines | Your primary testing document

Covers:

✅ Backend health checks (3 endpoints)
✅ Frontend login page accessibility
✅ Confession feed API and UI
✅ Confession detail page API and UI
✅ Report submission (unauthenticated endpoint)
✅ Admin route enforcement (with both success and failure scenarios)

Features:

Step-by-step instructions for each test
Expected results (PASS/FAIL) explicitly stated
Request/response examples (JSON format)
Prerequisites and dependencies called out
Evidence collection requirements (13 specific screenshots)
Quick validation notes for common issues
Regression test pattern for future releases

How to Use:

# Bookmark this as your primary guide
cat SMOKE_TEST_CHECKLIST.md

2. SMOKE_TEST_VALIDATION.md — Route Verification Report

303 lines | Codebase analysis proving all routes exist

Provides:

✅ Confirmation that every endpoint exists in codebase
✅ File paths and line numbers for each route
✅ Authentication guard verification
✅ Frontend page route confirmation
✅ Route status tables with source code references
✅ Known stale route risks and monitoring strategy

Content:

Backend route status (health, confessions, reports, admin)
Frontend route status (login, feed, detail, admin pages)
Configuration validation (ports, env vars)
Section-by-section validation status
Setup instructions for runtime testing

How to Use:

# Reference to validate routes haven't drifted from code
cat SMOKE_TEST_VALIDATION.md

3. SMOKE_TEST_CURL_GUIDE.md — Manual Testing Reference

402 lines | Copy-paste ready curl commands for every endpoint

Includes:

✅ Complete curl command for every endpoint tested
✅ Section-by-section breakdown matching checklist
✅ Sample request/response pairs
✅ Environment variable setup
✅ Troubleshooting guide
✅ Performance baseline template
✅ Batch testing script

Sections:

Health checks (3 endpoints)
Confession feed (list + create)
Confession detail (fetch + comment)
Report submission (4 report types)
Admin routes (3 auth scenarios)
Frontend URLs
Performance baseline recording

How to Use:

# Copy any command and run directly
export BACKEND_URL="http://localhost:5000"
curl -X GET "$BACKEND_URL/" -w "\nStatus: %{http_code}\n"

# Or run the batch script
cat SMOKE_TEST_CURL_GUIDE.md | grep "curl" | head -20

4. scripts/smoke-test.sh — Automated Test Suite

220 lines | Executable bash script for CI/CD integration

Features:

✅ Automated testing of all core endpoints
✅ Colorized output (green PASS, red FAIL, yellow pending)
✅ Test counter with pass rate calculation
✅ Results saved to file (smoke-test-results.txt)
✅ API requests logged (smoke-test-requests.log)
✅ Configurable backend/frontend URLs
✅ Exit codes for CI/CD pipelines (0=pass, 1=fail)

Sections:

Backend health checks
Confession API endpoints
Report submission
Admin endpoint access control
Frontend availability
Results summary with pass rate

How to Use:

# Make executable (already done)
chmod +x scripts/smoke-test.sh

# Run with default settings (localhost:5000 and :3000)
./scripts/smoke-test.sh

# Run with verbose output
./scripts/smoke-test.sh --verbose

# Run with custom URLs
BACKEND_URL="http://staging:5000" FRONTEND_URL="http://staging:3000" ./scripts/smoke-test.sh

# Integrate with CI/CD
if ./scripts/smoke-test.sh; then
  echo "✅ Smoke tests passed"
else
  echo "❌ Smoke tests failed"
  exit 1
fi

5. SMOKE_TEST_IMPLEMENTATION.md — Implementation Summary

336 lines | High-level overview of what was built

Contains:

✅ Acceptance criteria verification (all met)
✅ Files created/updated list with line counts
✅ Complete route verification table
✅ Usage instructions for each testing method
✅ Evidence package requirements
✅ PR documentation template
✅ Stale route risk assessment
✅ Performance baseline tracking

How to Use:

# Review what was built and how to use it
cat SMOKE_TEST_IMPLEMENTATION.md

# Check acceptance criteria
grep "^### ✅" SMOKE_TEST_IMPLEMENTATION.md

6. SMOKE_TEST_QUICK_REFERENCE.txt — One-Page Cheat Sheet

150 lines | Print-friendly quick reference card

Perfect for:

Wall posting next to desk
Bookmark on browser
Quick command lookup
Common issues reference

Includes:

One-liner quick commands
Endpoint table at a glance
Frontend URLs reference
Sample test data
Evidence checklist
Key files reference
Common issue solutions
Performance baseline form
PR comment template

How to Use:

# Print this
cat SMOKE_TEST_QUICK_REFERENCE.txt | lpr

# Or view in terminal
less SMOKE_TEST_QUICK_REFERENCE.txt

🎯 Acceptance Criteria - Complete Verification

Criterion	Evidence	Status
Checklist covers backend health	SMOKE_TEST_CHECKLIST.md, Section 1	✅
Checklist covers frontend login page	SMOKE_TEST_CHECKLIST.md, Section 2	✅
Checklist covers confession feed	SMOKE_TEST_CHECKLIST.md, Section 3	✅
Checklist covers detail page	SMOKE_TEST_CHECKLIST.md, Section 4	✅
Checklist covers reporting	SMOKE_TEST_CHECKLIST.md, Section 5	✅
Checklist covers one admin route	SMOKE_TEST_CHECKLIST.md, Section 6	✅
States expected pass/fail for unauthenticated	SMOKE_TEST_CHECKLIST.md, each section	✅
Includes evidence requirements	SMOKE_TEST_CHECKLIST.md, "Evidence Package for PR"	✅
Stale route names verified	SMOKE_TEST_VALIDATION.md route tables	✅
Ready for localhost validation	All sections, setup instructions	✅

🚀 Quick Start

For First-Time Users

# 1. Read the main checklist
cat SMOKE_TEST_CHECKLIST.md

# 2. Start your stack
docker compose -f compose.yaml up -d
npm run dev --workspace=xconfess-backend &
npm run dev --workspace=xconfess-frontend &

# 3. Run automated tests
./scripts/smoke-test.sh

For Manual Testing

# 1. Pick an endpoint from the curl guide
cat SMOKE_TEST_CURL_GUIDE.md

# 2. Copy a curl command and run it
export BACKEND_URL="http://localhost:5000"
curl -X GET "$BACKEND_URL/health/live" | jq .

# 3. Verify expected results
# (compare against SMOKE_TEST_CHECKLIST.md)

For Automated Testing

# 1. Execute script
./scripts/smoke-test.sh

# 2. Check results
cat smoke-test-results.txt
cat smoke-test-requests.log

# 3. Use for CI/CD
if ./scripts/smoke-test.sh; then echo "✅"; fi

For PR Documentation

# 1. Run all tests (manual or automated)
# 2. Collect evidence per SMOKE_TEST_CHECKLIST.md
# 3. Create folder: smoke-test-evidence/
# 4. Add 13 screenshots + summary + logs
# 5. Reference in PR: "See SMOKE_TEST_VALIDATION.md"

📊 Statistics

Metric	Value
Total Documentation	1,778 lines
Number of Files	6 documents
Endpoints Tested	10+ endpoints
Route Confirmations	20+ routes verified
Test Scenarios	30+ distinct tests
Evidence Screenshots	13 required
Setup Time	~15 minutes
Test Execution Time	2-5 minutes

🔄 How the Documents Work Together

START HERE
    ↓
SMOKE_TEST_QUICK_REFERENCE.txt (60 sec read)
    ↓
Decide: Manual or Automated?
    ├─→ MANUAL: SMOKE_TEST_CURL_GUIDE.md
    │            ↓
    │       (Copy curl commands, run, verify)
    │            ↓
    │       SMOKE_TEST_CHECKLIST.md
    │            ↓
    │       (Document results, capture screenshots)
    │
    └─→ AUTOMATED: scripts/smoke-test.sh
                   ↓
                 (Run script, check results.txt)
                   ↓
                 Review SMOKE_TEST_CHECKLIST.md
                   ↓
                 (Manual verify any failures)
                   
Need to verify routes exist? → SMOKE_TEST_VALIDATION.md
Need examples? → SMOKE_TEST_CURL_GUIDE.md
Need to understand what was built? → SMOKE_TEST_IMPLEMENTATION.md
Need to test now? → scripts/smoke-test.sh

🎓 Learning Path

Day 1: Understanding

Read: SMOKE_TEST_QUICK_REFERENCE.txt (5 min)
Read: SMOKE_TEST_CHECKLIST.md section 1 only (10 min)
Read: SMOKE_TEST_VALIDATION.md backend section (10 min)

Day 2: Manual Testing

Reference: SMOKE_TEST_CURL_GUIDE.md
Start: Local stack (Docker, backend, frontend)
Test: Follow checklist sections 1-3 (health, login, feed)
Document: Capture screenshots

Day 3: Complete Testing

Test: Remaining sections 4-6 (detail, reports, admin)
Run: Automated script ./scripts/smoke-test.sh
Verify: Results match expectations
Package: Evidence and upload to PR

Ongoing: Maintenance

Bookmark: SMOKE_TEST_QUICK_REFERENCE.txt
Run: ./scripts/smoke-test.sh before each PR
Update: Document if any routes change
Reference: SMOKE_TEST_VALIDATION.md for route lookups

🔍 Where to Find Specific Information

Question	File	Section
What endpoints do I test?	SMOKE_TEST_CHECKLIST.md	Sections 1-6
What's the curl command for...?	SMOKE_TEST_CURL_GUIDE.md	Matching section
Do the routes actually exist?	SMOKE_TEST_VALIDATION.md	Route verification
How do I run tests automatically?	scripts/smoke-test.sh	N/A (executable)
Quick command reference?	SMOKE_TEST_QUICK_REFERENCE.txt	One-liners section
Evidence requirements?	SMOKE_TEST_CHECKLIST.md	"Evidence Package for PR"
Common issues?	SMOKE_TEST_CURL_GUIDE.md	"Troubleshooting"
What was built?	SMOKE_TEST_IMPLEMENTATION.md	All sections

✨ Next Steps After Validation

Run against localhost (see Quick Start above)
Capture evidence (see SMOKE_TEST_CHECKLIST.md)
Document any differences (update SMOKE_TEST_VALIDATION.md if routes changed)
Attach to PR (include evidence folder + validation report)
Add to CI/CD (integrate scripts/smoke-test.sh into GitHub Actions)
Set baseline metrics (record response times for regression detection)
Automate in future (run smoke tests on every deploy candidate)

📝 Files at a Glance

SMOKE_TEST_CHECKLIST.md           367 lines  Main test guide
SMOKE_TEST_CURL_GUIDE.md           402 lines  Manual curl reference
SMOKE_TEST_VALIDATION.md           303 lines  Route verification
SMOKE_TEST_IMPLEMENTATION.md       336 lines  Build summary
SMOKE_TEST_QUICK_REFERENCE.txt     150 lines  One-page cheat sheet
scripts/smoke-test.sh              220 lines  Automated script

TOTAL: 1,778 lines of comprehensive documentation

Status: ✅ Complete and ready for localhost validation
Last Updated: 2026-05-29
Next Review: After first full test run
Maintainer: Development Team

Questions?

How do I run the smoke tests? → See Quick Start above
What if a test fails? → See SMOKE_TEST_CHECKLIST.md troubleshooting
How do I document results? → See SMOKE_TEST_CHECKLIST.md evidence section
Can I automate this? → Yes, use scripts/smoke-test.sh
What routes are tested? → See SMOKE_TEST_VALIDATION.md tables

FilesExpand file tree

SMOKE_TEST_INDEX.md

Latest commit

History

SMOKE_TEST_INDEX.md

File metadata and controls

Smoke Test Suite - Complete Documentation Index

📋 Core Documents

1. SMOKE_TEST_CHECKLIST.md — Main Testing Guide

2. SMOKE_TEST_VALIDATION.md — Route Verification Report

3. SMOKE_TEST_CURL_GUIDE.md — Manual Testing Reference

4. scripts/smoke-test.sh — Automated Test Suite

5. SMOKE_TEST_IMPLEMENTATION.md — Implementation Summary

6. SMOKE_TEST_QUICK_REFERENCE.txt — One-Page Cheat Sheet

🎯 Acceptance Criteria - Complete Verification

🚀 Quick Start

For First-Time Users

For Manual Testing

For Automated Testing

For PR Documentation

📊 Statistics

🔄 How the Documents Work Together

🎓 Learning Path

Day 1: Understanding

Day 2: Manual Testing

Day 3: Complete Testing

Ongoing: Maintenance

🔍 Where to Find Specific Information

✨ Next Steps After Validation

📝 Files at a Glance

Questions?