Testing & Docs Consolidation Summary

Date: January 17, 2026
Status: ✅ Complete

Overview

Consolidated fragmented testing documentation and created a clear single source of truth for each testing domain. All content is now organized with clear navigation and cross-references.

---

What Changed

1. Application Testing Documentation (NEW LOCATION)

Previous location: docs/engineering/testing/
New location: docs/engineering/guides/testing/

This reorganization clarifies that these are developer guides for testing application features, separate from unit tests and workflow automation.

Files moved:

• LOCAL_TESTING.md - Signup flows and manual testing
• CODE_COVERAGE_REFERENCE.md - Coverage reporting
• PIXEL_TESTING.md - Mobile device testing
• TEST_CROSS_DEVICE_SYNC.md - Multi-device profile sync testing
• VENUE_TESTING_GUIDE.md - Venue and lantern testing

New file added:

• README.md - Testing guide hub with navigation and best practices

---

2. Unit Tests Organization (CLARIFIED)

Location: src/__tests__/

New file added:

• README.md - Test organization, running tests, writing tests, and best practices

Scope clarified:

• Unit tests for components and utilities
• Vitest configuration
• Workflow-specific tests (AI triage, GitHub automation)
• Coverage reporting

---

3. GitHub Workflows Documentation Hub (NEW)

Location: docs/engineering/github/ (Navigation layer)
Actual content: .github/workflows/docs/ (Unchanged)

This creates a logical hierarchy in VitePress while keeping actual workflow files in .github/.

New files:

• docs/engineering/github/README.md - GitHub topics overview (future-proof for other GitHub topics)
• docs/engineering/github/workflows/README.md - Workflows navigation hub with links to .github/workflows/docs/

Benefits:

• VitePress sidebar shows: Engineering → GitHub → Workflows
• All workflow test scripts stay in .github/workflows/
• Content files stay in .github/workflows/docs/
• Navigation is clear without duplicating files

---

4. Updated Documentation Index

docs/DOCS_INDEX.md - Updated section on testing:

• Links to new testing guide location
• References to unit test README
• Links to new GitHub workflows hub
• Clarifies different testing types

docs/engineering/README.md - Updated directory structure:

• Reorganized testing section
• Added GitHub integration section
• Clarified testing guide locations

.github/workflows/docs/README.md - Added navigation note:

• Indicates content is also accessible from main docs
• Links back to the VitePress navigation

---

New Structure

Testing Documentation (Three Tiers)

1. Application Testing (Development Guides)
   docs/engineering/guides/testing/
   ├── README.md                      (Hub)
   ├── LOCAL_TESTING.md               (Manual testing)
   ├── TEST_CROSS_DEVICE_SYNC.md      (Profile sync)
   ├── VENUE_TESTING_GUIDE.md         (Features)
   ├── PIXEL_TESTING.md               (Mobile)
   └── CODE_COVERAGE_REFERENCE.md     (Coverage)

2. Unit Tests (Code Tests)
   src/__tests__/
   ├── README.md                      (Organization & setup)
   ├── *.test.jsx                     (Component tests)
   └── workflows/
       ├── *.test.js                  (Workflow tests)
       └── README.md                  (Workflow test guide)

3. Workflow Automation Tests (CI/CD)
   .github/workflows/
   ├── docs/
   │   ├── testing/                   (Test procedures)
   │   ├── ai-triage/                 (Implementation ref)
   │   └── discord/                   (Implementation ref)
   └── *.sh                           (Test scripts)

Navigation Hub:
   docs/engineering/github/workflows/README.md
   └── Links to .github/workflows/docs/

---

Single Source of Truth

Each domain now has ONE clear home:

Domain	Purpose	Location
Application Testing	Manual feature testing, signup flows, device testing	docs/engineering/guides/testing/
Unit Tests	Component and utility tests	src/__tests__/
Unit Test Organization	How tests are organized, running tests	src/__tests__/README.md
Workflow Tests	CI/CD automation testing	.github/workflows/docs/testing/
Workflow Automation	GitHub Actions, issue triage, Discord	.github/workflows/
Workflow Navigation	Easy discovery from VitePress	docs/engineering/github/workflows/

---

Cross-References Added

In Application Testing Guides

• Link to unit tests: src/__tests__/README.md
• Link to workflow automation: docs/engineering/github/workflows/
• Link to environment setup: docs/engineering/guides/ENVIRONMENT_SETUP.md

In Unit Tests

• Link to application testing: docs/engineering/guides/testing/
• Link to workflow tests: .github/workflows/docs/testing/
• Link to coverage: docs/engineering/guides/testing/CODE_COVERAGE_REFERENCE.md

In Workflow Docs

• Link to main docs: docs/engineering/github/workflows/
• Note in .github/workflows/docs/README.md about navigation

In VitePress Index

• Complete mapping of all testing locations
• Clear distinction between testing types
• Links to new navigation hub

---

Benefits of This Consolidation

✅ Clear Boundaries - Each testing type has its purpose and location
✅ No Duplication - Content lives in ONE place
✅ Easy Navigation - VitePress sidebar organizes logically
✅ Single Source of Truth - No confusion about where to find what
✅ Future-Proof - GitHub directory can grow with other topics
✅ Developer-Friendly - Clear README files explain organization
✅ Cross-Referencing - All docs link to related resources

---

Files Created/Modified

New Files

docs/engineering/github/README.md
docs/engineering/github/workflows/README.md
docs/engineering/guides/testing/README.md
docs/engineering/guides/testing/LOCAL_TESTING.md
docs/engineering/guides/testing/CODE_COVERAGE_REFERENCE.md
docs/engineering/guides/testing/PIXEL_TESTING.md
docs/engineering/guides/testing/TEST_CROSS_DEVICE_SYNC.md
docs/engineering/guides/testing/VENUE_TESTING_GUIDE.md
src/__tests__/README.md

Updated Files

docs/DOCS_INDEX.md
docs/engineering/README.md
.github/workflows/docs/README.md

---

Next Steps

Optional Cleanup

• The old docs/engineering/testing/ directory can be deleted after verifying links work
• Update VitePress sidebar configuration to auto-generate if needed

Maintenance

• Keep all READMEs current as new tests are added
• Update cross-references when moving files
• Use these READMEs as templates for new testing documentation

VitePress Sidebar

If using manual sidebar configuration, ensure these entries exist:

// Under Engineering
{
  text: 'GitHub',
  items: [
    {
      text: 'Workflows',
      link: '/engineering/github/workflows/'
    }
  ]
},
{
  text: 'Guides',
  items: [
    {
      text: 'Testing',
      link: '/engineering/guides/testing/'
    }
  ]
}

---

Summary

We've created a well-organized, clearly documented testing infrastructure with:

• Application Testing Guides in docs/engineering/guides/testing/ with comprehensive README
• Unit Tests organized in src/__tests__/ with setup and organization guide
• Workflow Automation Testing in .github/workflows/docs/ with testing procedures
• Navigation Hub in docs/engineering/github/workflows/ for easy VitePress discovery
• Cross-references throughout so developers can find exactly what they need

Result: Single source of truth for each testing domain. Clear navigation. No duplication.