Skip to content

README_TOOLS.md

Latest commit

 

History

History
256 lines (184 loc) · 7.45 KB

README_TOOLS.md

File metadata and controls

256 lines (184 loc) · 7.45 KB

API Documentation & Testing Tools - Quick Reference

Status: ✅ ALL WORKING - Phase 1 Complete!

🚀 Quick Start

Check Your API Coverage

npm run docs:coverage

Shows which of your 108 API methods are documented and tested.

  • Tracks API.md documentation (48% - 52 methods)
  • Tracks JSDoc documentation (0% - ready to add)
  • Shows test coverage (49% - 53 methods)

Run Automated Tests

npm run test:api @notslow    # Run all fast tests (100 tests)
npm run test:api babylon     # Run specific test suite
npm run test:api @onlyslow   # Run all slow tests (94 tests)
npm run test:api glide -- --log-all --verbose  # With detailed logging

Security Validation for External Links

npm run check:link-security

Enforces the project rule for external navigation hardening:

  • Every <a target="_blank"> in index.html must include rel="noopener noreferrer".
  • Every audited window.open(...) call in index.html and ui/designview.js must include a third argument containing both noopener and noreferrer.
  • This check also runs as part of npm run lint so PRs fail fast if protections are missing.

✅ What's Working

1. Coverage Report Tool

  • Analyzes 108 API methods
  • Shows 48% API.md documentation (52 methods)
  • Shows 0% JSDoc coverage (ready to add)
  • Shows 49% test coverage (53 methods)
  • Generates reports/api-coverage.md
  • Tracks both API.md and JSDoc separately!

2. CLI Test Runner

  • Runs tests in headless browser
  • Automatic server management with CI support
  • Full test result reporting
  • 100% functional! 🎉
  • All 226 tests running successfully!
  • Supports logging (--log-api, --log-tests, --log-all)
  • CI-ready: Works reliably in GitHub Actions (fixed Nov 2025)

3. All Utilities

  • Method extraction from flock.js
  • JSDoc parsing from api/*.js
  • API.md documentation parsing (NEW!)
  • Test coverage analysis

📚 Documentation

File Purpose
docs/API_QUALITY_TOOLS.md ⭐ PRIMARY GUIDE - Start here!
docs/GETTING_STARTED.md Quick start for improving API quality
docs/API_RECONCILIATION_PLAN.md Strategy and approach
docs/IMPLEMENTATION_STATUS.md Current metrics and status
docs/archive/ Historical investigation docs

🎯 What to Do Next

Option A: Check Coverage

npm run docs:coverage

Review the report to see what needs work.

  • Shows which methods lack API.md documentation
  • Shows which methods lack JSDoc documentation
  • Shows which methods lack tests

Option B: Run Tests

npm run test:api @notslow    # All fast tests (100 tests)
npm run test:api babylon     # Specific suite (3 tests)

Verify tests run successfully on your system.

Option C: Read the Primary Guide Open docs/API_QUALITY_TOOLS.md ⭐ for the complete guide on using these tools.

📊 Current Metrics

  • Total API Methods: 108
  • Documented (API.md): 52 (48%)
  • Documented (JSDoc): 0 (0%)
  • Tested: 53 (49%)
  • Untested: 55 (51%)
  • Test Files: 15
  • Total Tests: 226 (all running successfully!)

🎉 Key Achievements

Phase 1 Complete ✅

All Infrastructure Operational:

  1. ✅ Coverage tracking works - Tracks both API.md and JSDoc
  2. ✅ Test runner 100% functional - All 226 tests running
  3. ✅ Logging infrastructure - Debug API calls and test execution
  4. ✅ Clean documentation - Primary guide + historical archive

Issues Resolved:

  • ✅ HTTP 500 error (fixed via npm install)
  • ✅ Test runner premature exit (fixed waitForFunction)
  • ✅ @slow tests only running 1 test (now all 94 running!)
  • ✅ Documentation tracking showing 0% (now shows 48% API.md coverage)

Verified Test Suites:

  • ✅ @notslow: 100 tests running
  • ✅ @onlyslow: 94 tests running (89 passing, 5 legitimate failures)
  • ✅ babylon: 3 tests passing
  • ✅ materials: 22 tests passing
  • ✅ physics: 6 tests running (4 passing, 2 expected failures)
  • ✅ glide: 5 tests passing
  • ✅ sound: 15 tests running
  • ✅ All suites operational!

💪 Tools Available

# Coverage analysis
npm run docs:coverage

# Run tests (automated, headless)
npm run test:api @notslow           # Fast tests (100 tests)
npm run test:api @onlyslow          # Slow tests (94 tests)
npm run test:api babylon            # Specific suite
npm run test:api glide -- --log-all # With logging

# Logging options
--log-api      # Log API method calls
--log-tests    # Log test execution
--log-all      # Both logs
--verbose      # Additional diagnostics

🔍 Example Output

Coverage Report

📊 Total API Methods: 108
📖 API.md Documentation: 52 methods

Summary Statistics:
  ✅ Documented:       52 (48%)
     ├─ API.md only:   52 methods
     ├─ JSDoc only:    0 methods
     └─ Both:          0 methods
  ✅ Tested:           53 (49%)
  ❌ Undocumented:     56 (52%)
  ❌ Untested:         55 (51%)

Test Runner

╔════════════════════════════════════════╗
║     Flock XR API Test Runner          ║
╚════════════════════════════════════════╝

✅ Development server started
✅ Test page loaded
✅ Flock initialized and tests loaded

🧪 Running test suite: babylon

┌─────────────────────────────────────┐
│         Test Results                │
└─────────────────────────────────────┘

  Total Tests:     3
  ✅ Passing:      3
  ❌ Failing:      0

✅ All tests passed!

📁 Project Files

Scripts:

  • scripts/api-coverage-report.mjs - Coverage analysis
  • scripts/run-api-tests.mjs - CLI test runner
  • scripts/utils/extract-api-methods.mjs - Extract API methods
  • scripts/utils/parse-jsdoc.mjs - Parse JSDoc
  • scripts/utils/parse-api-md.mjs - Parse API.md (NEW!)
  • scripts/utils/test-analyzer.mjs - Test coverage analysis

Documentation:

  • dev-docs/archive/github-ci-debugging/TEST_RUNNER_CI_FIX_SUMMARY.md - CI/GitHub Actions fix (Nov 2025)
  • dev-docs/archive/github-ci-debugging/TEST_RUNNER_SERVER_STARTUP.md - Server startup technical details
  • docs/docs.md - User documentation
  • docs/models.md - 3D models documentation

Reports:

  • reports/api-coverage.md - Generated coverage report
  • logs/api-calls.log - API call logging (when enabled)
  • logs/test-execution.log - Test execution logging (when enabled)

🚀 Phase 2 - What's Next?

Now that infrastructure is complete, focus on:

  1. Add JSDoc to API methods (currently 0%)

    • Start with most-used methods
    • Use templates in docs/API_QUALITY_TOOLS.md
    • Target: 80% JSDoc coverage

  2. Write tests for untested categories

    • Mesh operations (0% tested - 8 methods)
    • Camera (0% tested - 3 methods)
    • Movement (0% tested - 3 methods)
    • Shapes (0% tested - 4 methods)
    • Target: 80% test coverage

  3. Expand API.md documentation

    • Document high-priority methods
    • Target: 80% API.md coverage

Everything is working!

Run tests: npm run test:api babylon

For CI/GitHub Actions: See docs/TEST_RUNNER_CI_FIX_SUMMARY.md ⭐