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

If using manual sidebar configuration, ensure these entries exist:

javascript

// 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.

Testing & Docs Consolidation Summary ​

Overview ​

What Changed ​

1. Application Testing Documentation (NEW LOCATION) ​

2. Unit Tests Organization (CLARIFIED) ​

3. GitHub Workflows Documentation Hub (NEW) ​

4. Updated Documentation Index ​

New Structure ​

Testing Documentation (Three Tiers) ​

Single Source of Truth ​

Cross-References Added ​

In Application Testing Guides ​

In Unit Tests ​

In Workflow Docs ​

In VitePress Index ​

Benefits of This Consolidation ​

Files Created/Modified ​

New Files ​

Updated Files ​

Next Steps ​

Optional Cleanup ​

Maintenance ​

VitePress Sidebar ​

Summary ​