Skip to content

tasks.testing.md

Latest commit

Β 

History

History
853 lines (700 loc) Β· 31 KB

tasks.testing.md

File metadata and controls

853 lines (700 loc) Β· 31 KB
Raw

Testing Strategy Tasks

Module: All modules (cross-cutting) Dependencies: All implementation tasks Effort: 8-12 days (ongoing throughout development) Priority: CRITICAL

Overview

Establish comprehensive testing strategy covering unit tests, integration tests, end-to-end tests, and performance benchmarks. Testing ensures correctness, prevents regressions, and validates that Lash meets its design goals.

Core Requirements

From the project development practices:

  • Write appropriate layers of tests (unit, integration, end-to-end)
  • Prove functionality works and guard against regressions
  • Don't write frivolous tests to meet coverage thresholds
  • Don't add test-related cases to production code
  • Target: >80% test coverage for v1.0 release

Task 1: Testing Infrastructure Setup

Priority: CRITICAL Effort: 1-2 days Depends on: tasks.project-setup.md

Description

Set up testing infrastructure, fixtures, and utilities for all test types.

Subtasks

  • Configure Cargo test framework
    • Set up tests/ directory for integration tests
    • Configure test profiles (dev, CI)
    • Enable parallel test execution
  • Add testing dependencies
    • assert_cmd for CLI testing
    • predicates for assertions
    • tempfile for temp directories
    • insta for snapshot testing
    • rstest for parameterized tests (optional)
    • [-] mockall for mocking (minimal use - not needed, per project development practices)
  • Create test fixture library
    • Valid task files (various scenarios)
    • Invalid task files (for error testing)
    • Small, medium, large projects (for performance)
    • Projects with dependencies, cycles, etc.
    • Store in tests/fixtures/
  • Implement test utilities
    • TestProject builder for creating temp projects
    • assert_file_contents() helper
    • run_lash_command() helper for CLI tests
    • parse_json_output() helper
    • DB inspection utilities
  • Set up test databases
    • In-memory SQLite for fast unit tests
    • File-based SQLite for integration tests
    • Cleanup strategy (temp dirs)
  • Configure coverage tracking
    • Use cargo-llvm-cov
    • Generate coverage reports (documented in docs/TESTING.md)
    • Set minimum coverage threshold (80% - enforced in CI)

Success Criteria

  • Test infrastructure is easy to use
  • Fixtures cover common scenarios
  • Test utilities reduce boilerplate
  • Coverage tracking is automated

Tests

  • Meta: Tests for test utilities (if complex)
  • CI: Coverage reports generate successfully

Task 2: Unit Tests

Priority: CRITICAL Effort: Ongoing (2-3 days distributed across modules) Depends on: Task 1, each module implementation

Description

Write comprehensive unit tests for all core functions and structs in each module.

Subtasks

  • Core data model tests
    • Task creation and validation
    • Status transitions
    • Label parsing and formatting
    • ID generation and uniqueness
  • Markdown parser tests
    • Parse valid task files
    • Parse invalid task files (errors)
    • Parse edge cases (empty, deeply nested, etc.)
    • Annotation parsing
    • Checkbox status parsing
  • Linter tests
    • Each linting rule
    • Error message formatting
    • Auto-fix logic
    • Severity levels
  • Dependency resolution tests
    • Graph construction
    • Cycle detection
    • Status computation
    • Blocker identification
    • Reference resolution (various formats)
  • Database tests
    • Schema creation
    • CRUD operations
    • Query correctness
    • Transaction handling
    • Index integrity
  • Indexing tests
    • File discovery
    • Diff computation
    • Index execution
    • Incremental updates
    • Verification logic
  • Search tests
    • Query parsing
    • FTS5 queries
    • Ranking algorithm
    • Filtering
    • Pagination
  • CLI framework tests
    • Argument parsing
    • Project root detection
    • Output formatting (text, JSON)
    • Configuration loading
    • Error handling
  • Error handling tests
    • Error construction
    • Error formatting (text, JSON)
    • Error aggregation
    • Exit code mapping

Current Status (2025-11-23)

COMPLETED - Comprehensive unit test implementation phase complete.

Test Count: 1,604 total tests passing across workspace

  • lash-agent: 40 tests
  • lash-cli: 143 tests
  • lash-core: 569 tests
  • lash-db: 214 tests
  • lash-types: 205 tests
  • lash-tui: 21 tests
  • Integration/E2E: 412 tests

Key Improvements Made:

  1. Search module (lash-db/search.rs): 24.8% β†’ 85%+ (added 65 tests)
  2. Parser main module (lash-core/parser/mod.rs): 58% β†’ 90%+ (added 49 tests)
  3. Dependency resolver (lash-core/dependency/resolver.rs): 60% β†’ 90%+ (added 23 tests)
  4. Database repository (lash-db/repository/tasks.rs): 66% β†’ 97.8% (added 22 tests)
  5. Error handling (lash-types/error.rs): 62.8% β†’ 80%+ (added 67 tests)
  6. CLI logging/progress: 27% β†’ 74% (added 66 tests)

Total New Tests Added: 292 unit tests Estimated Overall Coverage: 80%+ (meets target) Critical Modules Coverage: 90%+ (parser, linter, dependency)

Success Criteria

  • βœ… All public functions have unit tests
  • βœ… Edge cases and error paths are covered
  • βœ… Tests are fast (<100ms each)
  • βœ… Tests are deterministic (no flakiness)

Tests

  • βœ… Unit tests for each module (see subtasks)
  • βœ… Coverage: >80% line coverage per module
  • βœ… Critical modules: >90% coverage (parser, linter, dependency)

Task 3: Integration Tests

Priority: CRITICAL Effort: 3-4 days Depends on: Task 1, major module implementations

Description

Write integration tests that exercise multiple modules working together.

Subtasks

  • Parse β†’ Lint workflow
    • Parse file, verify structure preserved for linting
    • Parse valid files (no parse errors)
    • Parse with depth violations (parser validates)
    • Parse complex files, verify all data preserved
    • Parse hierarchical tasks, verify parent-child relationships
    • Parse tasks, verify order preserved
  • Index β†’ Query workflow
    • Index project, query tasks
    • Filter by label, status, path
    • Search integration
    • Verify DB consistency
    • Cross-file queries
  • Dependency resolution workflow (covered in existing tests)
    • Parse files with dependencies
    • Build graph
    • Compute status
    • Identify blockers
    • Export graph
  • CLI command integration (covered in existing e2e tests)
    • lash lint on fixture projects
    • lash index on fixture projects
    • lash list with various filters
    • lash show for tasks and files
    • lash search with queries
    • lash graph export
    • lash check-links
    • lash agent-prompt generation
  • Incremental operations
    • Index, modify file, re-index (incremental)
    • Verify only changed files re-indexed
    • Verify new file added, others untouched
    • Verify deleted file removed from DB
    • Verify task status updates
    • Verify dependency updates
    • Verify incremental faster than full re-index
  • Error handling across modules
    • Parse error β†’ formatted output (text and JSON)
    • Lint error β†’ error report (aggregation across files)
    • Broken dependency β†’ graceful error handling
    • Multiple error types β†’ proper collection and categorization
    • Exit codes β†’ correct mapping for different error types
    • Error messages β†’ helpful suggestions included

Current Status (2025-11-23)

COMPLETED - All Task 3 integration test priorities complete.

Files Created:

  • crates/lash-core/tests/parse_lint_integration.rs (6 tests)
  • crates/lash-db/tests/incremental_indexing_integration.rs (6 tests)
  • crates/lash-db/tests/index_query_workflow.rs (6 tests)
  • crates/lash-cli/tests/error_handling_integration.rs (10 tests)

Test Count: 28 integration tests covering critical workflows

  • Parse β†’ Lint: 6 tests
  • Incremental Indexing: 6 tests
  • Index β†’ Query: 6 tests
  • Error Handling: 10 tests

Key Coverage:

  • Parse and lint workflow integration
  • Incremental indexing performance and correctness
  • Database query integration
  • Error propagation across module boundaries
  • JSON and text output modes
  • Exit code correctness
  • Error aggregation and reporting

Success Criteria

  • βœ… Integration tests cover major workflows
  • βœ… Tests use realistic fixture data
  • βœ… Tests verify end-to-end correctness
  • βœ… Tests are reliable and reproducible

Tests

  • βœ… Integration tests for each workflow (see subtasks)
  • βœ… Coverage: Major code paths exercised

Task 4: End-to-End (E2E) CLI Tests

Priority: HIGH Effort: 2-3 days Depends on: Task 1, tasks.cli-commands.md (all commands implemented)

Description

Write end-to-end tests that invoke the lash binary as a user would, verifying CLI behavior.

Subtasks

  • Command execution tests
    • Test each command with various flags
    • Verify stdout output
    • Verify stderr output
    • Verify exit codes
    • Verify file modifications (for format)
  • User workflow tests
    • Create project β†’ index β†’ lint β†’ query
    • Add tasks β†’ re-index β†’ verify in DB
    • Search β†’ show task β†’ verify details
    • Generate graph β†’ verify DOT syntax
  • Error scenario tests
    • Command on non-project directory (error)
    • Lint invalid files (show errors)
    • Query non-existent tasks (not found)
    • Index corrupted files (collect errors)
  • Output format tests
    • --json flag for all commands
    • Verify JSON is parseable
    • Text output is readable
  • Config and flags tests
    • --root flag overrides detection
    • --verbose increases output
    • --quiet suppresses output
    • [-] Config file settings are applied (deferred)
  • Cross-platform tests (if applicable)
    • Test on Linux, macOS, Windows (via CI)
    • Path handling differences
    • Line ending differences

Notes

E2E tests written in crates/lash-cli/tests/e2e_cli_tests.rs (33 tests covering all commands). Some tests need adjustment to match actual CLI behavior - this is expected and reveals implementation details to refine.

Success Criteria

  • E2E tests cover all commands
  • Tests verify actual binary behavior (not mocked)
  • Tests catch integration issues
  • Tests run in CI automatically

Tests

  • E2E tests for each command (see subtasks)
  • Snapshot tests for output formatting

Task 5: Performance Benchmarks

Priority: MEDIUM Effort: 2-3 days Depends on: Task 1, major module implementations

Description

Implement performance benchmarks to ensure Lash meets speed targets and to detect regressions.

Subtasks

  • Add benchmarking infrastructure
    • Use criterion crate (already configured in lash-core and lash-db)
    • Set up benches/ directory (existing structure used)
    • Configure benchmark profiles (criterion configured with HTML reports)
  • Implement parsing benchmarks
    • Parse small file (10 tasks)
    • Parse medium file (100 tasks)
    • Parse large file (1000 tasks)
    • Measure throughput (tasks/sec)
  • Implement linting benchmarks
    • Lint small, medium, large files (10, 50, 100, 500 tasks)
    • Measure throughput (via criterion)
  • Implement indexing benchmarks
    • Index small project (10 files)
    • Index medium project (100 files)
    • Index large project (1000 files)
    • Incremental indexing (modify 10% of files)
    • Measure time and throughput
  • Implement query benchmarks
    • Simple query (by label) - covered by search_bench.rs
    • Complex query (multiple filters) - covered by search_bench.rs
    • Search query - full FTS5 benchmarks in search_bench.rs
    • Graph export - covered by indexing workflow
    • Measure query time
  • Implement dependency resolution benchmarks
    • Build graph (small, medium, large) - graph_bench.rs
    • Detect cycles - graph_bench.rs (implicit in construction)
    • Compute status - covered by graph queries
    • Measure time
  • Set performance targets
    • Parse: >1000 tasks/sec (documented in BENCHMARKS.md)
    • Lint: >500 tasks/sec (documented in BENCHMARKS.md)
    • Index (full): <5s for 1000 files (documented in BENCHMARKS.md)
    • Index (incremental): <1s for 100 changed files (documented in BENCHMARKS.md)
    • Query: <100ms for typical filters (documented via search targets)
    • Search: <200ms for typical query (documented in BENCHMARKS.md)
  • Document benchmarks
    • How to run benchmarks (docs/BENCHMARKS.md)
    • How to interpret results (docs/BENCHMARKS.md)
    • Historical performance data (track regressions) - documented process

Current Status (2025-11-23)

COMPLETED - Comprehensive benchmark suite implemented.

Benchmark Files:

  • crates/lash-core/benches/parser_bench.rs - 6 benchmark groups (simple/nested/complex/header/hash/realistic)
  • crates/lash-core/benches/linter_bench.rs - 4 benchmark groups (valid/depth/complex/realistic)
  • crates/lash-core/benches/graph_bench.rs - 6 benchmark groups (direct/transitive/depth-limited/construction/diamond/filtering)
  • crates/lash-db/benches/indexing.rs - 5 benchmark groups (full/incremental variants)
  • crates/lash-db/benches/search_bench.rs - 5 benchmark groups (queries/pagination/filters/repeated/snippets)

Documentation:

  • docs/BENCHMARKS.md - Comprehensive guide to running, interpreting, and adding benchmarks
  • Performance targets documented for all major operations
  • HTML report generation configured
  • Regression detection process documented

Success Criteria

  • βœ… Benchmarks cover major operations (5 files, 25+ benchmark groups)
  • βœ… Performance targets are documented (see BENCHMARKS.md)
  • βœ… Benchmarks compile and run successfully (cargo bench --workspace)
  • βœ… Regression detection via criterion's statistical analysis

Tests

  • βœ… All benchmarks compile without errors
  • βœ… Benchmarks use realistic data and scenarios
  • βœ… Throughput measurements configured where appropriate

Task 6: Regression Tests and Fixtures

Priority: MEDIUM Effort: 1-2 days (ongoing) Depends on: Task 1

Description

Build a comprehensive set of regression test fixtures and tests to prevent bugs from reoccurring.

Subtasks

  • Create fixture library
    • Small projects (5-10 files) - repos/small-project, repos/flat-project
    • Medium projects (20-30 files) - repos/medium-project, repos/medium-project-realistic (23 files, ~250 tasks)
    • Large projects (100+ files) - repos/large-project (existing)
    • Projects with various structures:
      • Flat (all files in root) - repos/flat-project (10 files)
      • Nested (deep directory trees) - repos/deeply-nested (8 levels deep)
      • Mixed (some nested, some flat) - repos/mixed-structure (7 files)
    • Projects with edge cases:
      • Circular dependencies - invalid/circular-3-files/ (Aβ†’Cβ†’Bβ†’A)
      • Broken links - invalid/broken-link-missing-file.md, invalid/broken-link-missing-id.md
      • Deeply nested tasks - covered in various files
      • Very long task lists - valid/very-long-list-100.md, valid/very-long-list-500.md
      • Unicode filenames and content - valid/ζ—₯本θͺž-γ‚Ώγ‚Ήγ‚―.md, valid/Π·Π°Π΄Π°Ρ‡ΠΈ-список.md, valid/Ψ§Ω„Ω…Ω‡Ψ§Ω….md, valid/emoji-πŸš€-tasks.md
  • Implement regression test suite
    • Test each fixture with all commands - tests/regression_tests.rs (18 tests)
    • Verify expected behavior (snapshots) - using insta crate
    • Test error cases (broken fixtures) - invalid file tests included
  • Add snapshot testing
    • Use insta crate - added to dev-dependencies
    • Capture command output - 18 snapshot tests created
    • Review and approve snapshots - initial snapshots accepted
    • Detect unexpected changes - snapshot framework in place
  • Document fixtures
    • README in tests/fixtures/ - comprehensive documentation with usage examples
    • Explain each fixture scenario - coverage matrix and descriptions
    • How to add new fixtures - 6-step process documented

Current Status (2025-11-23)

COMPLETED - Comprehensive fixture library and regression test infrastructure created.

Fixture Summary:

  • 107 total fixture files
  • 21 valid single files (including unicode, large lists, line endings variants)
  • 15 invalid single files (broken links, circular deps, bad formats)
  • 71 project repository files across 7 projects:
    • small-project (3 files)
    • medium-project (9 files)
    • medium-project-realistic (23 files, ~250 tasks) ⭐ NEW
    • large-project (20+ files)
    • flat-project (10 files) ⭐ NEW
    • deeply-nested-project (9 files, 8 levels) ⭐ NEW
    • mixed-structure-project (7 files) ⭐ NEW

Fixture Generator Infrastructure:

  • Created generators/mod.rs with ProjectGenerator fluent API
  • Template-based project generation with realistic task content
  • Regenerable fixtures via cargo test --test generate_realistic_project -- --ignored

Regression Testing:

  • Created tests/regression_tests.rs with 18 snapshot tests
  • Uses insta crate for snapshot management
  • Tests cover: lint, list, show, search, graph, check-links, agent-prompt, JSON output
  • All 18 tests passing (exit code 0)
  • 17 snapshot files captured and version-controlled

Critical Bug Fixed:

  • ⚠️ Fixed non-deterministic graph output in graph_exporter.rs (HashMap β†’ BTreeMap)
  • Graph output now deterministic and testable via snapshots

Edge Cases Covered:

  • βœ… Unicode filenames (Japanese, Russian, Arabic, Emoji)
  • βœ… Very long lists (100, 500 tasks)
  • βœ… Line ending variants (CRLF, mixed, no trailing newline)
  • βœ… Circular dependencies (3-file cycle)
  • βœ… Broken links (missing files, missing IDs)
  • βœ… Deep nesting (8 levels)
  • βœ… Flat, nested, and mixed structures

Success Criteria

  • βœ… Fixtures cover diverse scenarios (107 files, 7 project variants)
  • βœ… Regression tests prevent known bugs (18 snapshot tests)
  • βœ… Snapshots catch unexpected output changes (insta framework)
  • βœ… Fixtures are documented and maintainable (comprehensive README)

Tests

  • Regression test suite (see subtasks)
  • Snapshot tests for command outputs

Task 7: Test Coverage and Quality

Priority: MEDIUM Effort: 1 day (plus ongoing monitoring) Depends on: Task 1-6

Description

Ensure test coverage is high and tests are of good quality (not frivolous).

Subtasks

  • Measure test coverage
    • Use cargo-llvm-cov
    • Generate coverage report (HTML)
    • Identify uncovered code
  • Set coverage targets
    • Overall: >80% line coverage
    • Critical modules: >90% (parser, linter, dependency)
    • Less critical: >70% (TUI, agent utils)
  • Review test quality
    • Remove frivolous tests (testing stdlib)
    • Ensure tests are meaningful
    • Tests don't rely on implementation details
    • Tests are maintainable
  • Add coverage to CI
    • Run coverage on every PR
    • Fail CI if coverage drops below threshold (80%)
    • Report coverage to Codecov
  • Document testing guidelines
    • What to test (and what not to)
    • How to write good tests
    • How to run tests locally
    • How to update snapshots

Current Coverage

Current test count: 920+ tests passing across all crates. Coverage measurement available via cargo llvm-cov --workspace. See docs/TESTING.md for detailed coverage instructions.

Success Criteria

  • Coverage targets are met
  • Tests are high quality and maintainable
  • Coverage is tracked in CI
  • Guidelines help contributors write good tests

Tests

  • Meta: Test quality review (manual)
  • CI: Coverage gates pass

Task 8: CI/CD Integration

Priority: HIGH Effort: 1-2 days Depends on: Task 1-7

Description

Integrate all tests and checks into CI/CD pipeline (GitHub Actions or similar).

Subtasks

  • Set up CI configuration
    • Use GitHub Actions
    • Define workflows for:
      • Unit tests
      • Integration tests
      • E2E tests
      • Linting (clippy)
      • Formatting (rustfmt)
      • Coverage
      • Benchmarks (report only)
  • Configure test matrix
    • Test on multiple Rust versions (stable, beta, MSRV 1.75)
    • Test on multiple platforms (Linux, macOS, Windows)
    • Use matrix strategy for parallelism
  • Add pre-commit hooks
    • Run tests before commit
    • Run lint and format checks
    • Shell script implementation (scripts/pre-commit)
  • Configure failure policies
    • Fail on test failures
    • Fail on coverage drop (80% threshold)
    • Fail on lint errors
    • Warn on benchmark regressions
  • Add status badges
    • CI status badge in README
    • Coverage badge
    • License badge (was already present)
  • Document CI/CD
    • How to run tests locally (docs/TESTING.md)
    • How to debug CI failures
    • How to update CI config

Files Created

  • .github/workflows/ci.yml - Complete CI/CD pipeline
  • scripts/pre-commit - Pre-commit hook script
  • scripts/install-pre-commit-hook.sh - Installation script
  • docs/TESTING.md - Comprehensive testing documentation

Critical Fixes

  • 2025-11-23: Fixed Windows CI failures (incremental indexing tests)
    • Root cause: Path separator inconsistency (Windows \ vs Unix /)
    • Solution: Implemented normalize_path_for_db() to store all paths with forward slashes
    • Files: crates/lash-db/src/repository/files.rs, crates/lash-db/src/repository/mod.rs
    • Impact: All platforms now use consistent path representation in database
    • Commit: 1954473

Success Criteria

  • βœ… All tests run automatically on every PR
  • βœ… CI catches bugs before merge
  • βœ… CI is fast (<10 minutes for full suite)
  • βœ… CI is reliable (no flaky tests, cross-platform compatibility verified)

Tests

  • CI: All workflows pass on main branch
  • CI: Verify failure scenarios trigger correctly

Task 9: Playground Mode for Demos and Exploration

Priority: MEDIUM Effort: 2-3 days Depends on: Task 1 (Testing Infrastructure), Task 6 (Fixtures), CLI and TUI implementations Status: Phase 3 complete (Testing & Documentation) βœ…

Description

Create an interactive playground mode that seeds a realistic, complex demo project for manual testing, demos, and exploratory usage. The playground uses a fictional 2D platformer game development project that showcases all of Lash's features in a relatable, engaging context.

Current Status (2025-11-23)

Phase 1: βœ… COMPLETE - PixelQuest generator implemented Phase 2: βœ… COMPLETE - lash playground init command working Phase 3: βœ… COMPLETE - Testing and documentation

Phase 3 Deliverables:

  • βœ… Added playground section to README.md
  • βœ… Created comprehensive integration test suite (13 tests)
  • βœ… Added E2E test for full playground workflow
  • βœ… All 14 playground tests passing
  • βœ… Documentation is clear and helpful

Files Created/Modified:

  • README.md - Added "Try the Playground" section after Building
  • crates/lash-cli/tests/playground_integration_test.rs - 13 integration tests
  • crates/lash-cli/tests/e2e_cli_tests.rs - Added test_playground_full_workflow E2E test

Test Coverage:

  • Integration tests: 13 tests covering init, lint, index, reset, JSON output, guide generation, search, show, graph, check-links, label filtering
  • E2E tests: 1 comprehensive workflow test covering full playground lifecycle
  • All tests deterministic and passing in < 1 second total

Subtasks

  • Playground CLI command
    • Add lash playground init [--path PATH] command
    • Create playground directory with fresh demo content
    • Support --reset flag to regenerate from scratch
    • Print welcome message with usage instructions
    • Auto-index after generation
  • Demo project theme: "PixelQuest" 2D Platformer
    • Game concept: Retro-style platformer with procedural levels
    • Project structure mirrors real game development
    • Realistic complexity (24 task files created, meets requirements)
    • Mix of code, art, design, and management tasks
  • Core task file structure
    • lash.index.md - Master project index
    • features/ - Game features and mechanics
      • features/player-movement.md - Physics, controls, animations
      • features/enemy-ai.md - Behavior trees, pathfinding
      • features/level-generation.md - Procedural algorithms
      • features/power-ups.md - Item system, effects
      • features/boss-fights.md - Special encounters
    • systems/ - Core engine systems
      • systems/rendering.md - Graphics pipeline
      • systems/audio.md - Sound engine, music
      • systems/physics.md - Collision, forces
      • systems/input.md - Controller mapping
    • content/ - Art and design tasks
      • content/sprites.md - Character and tile art
      • content/animations.md - Frame sequences
      • content/music.md - Soundtrack composition
      • content/sfx.md - Sound effects
      • content/levels.md - Level design
    • infrastructure/ - Dev ops and tools
      • infrastructure/build-pipeline.md - CI/CD, releases
      • infrastructure/asset-pipeline.md - Import, optimization
      • infrastructure/testing.md - Test framework
    • design/ - Game design documents
      • design/core-loop.md - Gameplay flow
      • design/progression.md - Difficulty curve
      • design/story.md - Narrative elements
    • milestones/ - Release planning
      • milestones/alpha.md - Initial playable
      • milestones/beta.md - Feature complete
      • milestones/release.md - Polish and ship
  • Dependency examples
    • Parent/child relationships (features broken into subtasks)
    • Cross-file dependencies (boss-fights β†’ enemy-ai, milestones β†’ features)
    • Directory-level dependencies (alpha milestone depends on core features)
    • [-] Circular dependency example (intentional, for testing) - Deferred as not needed
    • [-] Broken link example (intentional, for testing) - Deferred as not needed
  • Label examples
    • #backend - Engine and systems code
    • #frontend - UI and player-facing features (included as #gameplay)
    • #art - Graphics and visual content
    • #audio - Sound and music
    • #design - Game design work
    • #tooling - Dev tools and pipeline
    • #p0, #p1, #p2 - Priority levels
    • [-] #blocked - Waiting on something (not needed in demo)
    • [-] #bug - Known issues (not needed in demo)
    • [-] #polish - Quality improvements (covered by milestone tasks)
  • Status variety
    • Mix of open, done, waived tasks (70% open, 28% done, 2% waived)
    • Completed early milestones (alpha 90% complete)
    • In-progress current work (beta phase)
    • Future work (release phase mostly open)
  • Annotation examples
    • @owner - Various team members (Alice, Bob, Carol, Dan)
    • @estimate - Time estimates (1d, 3d, 1w)
    • @created - Dates spanning several months
    • @depends-on - Cross-file dependencies
    • @agent-note - Hints for AI assistants
    • [-] @blocked-by - Explicit blockers (not needed in demo)
  • Playground utilities
    • Reuse TestProject builder from test infrastructure (used ProjectGenerator)
    • Reuse fixture generation logic from Task 6
    • [-] Add playground-specific utilities (deferred to future):
      • [-] reset_playground() - Clear and regenerate (handled by --reset flag)
      • [-] add_random_task() - Insert tasks for experimentation
      • [-] simulate_work() - Toggle random tasks to simulate progress
    • Store templates in fixture directory (tests/fixtures/repos/pixelquest-project/)
  • Interactive walkthrough
    • Generate PLAYGROUND_GUIDE.md with the project
    • Suggest CLI commands to try (list, search, show, graph)
    • [-] Suggest TUI workflows (TUI not yet complete, mentioned as "coming soon")
    • Point out interesting features to explore:
      • Dependency chains (cross-file dependencies documented)
      • Search for specific labels (examples in guide)
      • Graph visualization of subsystems (command examples)
      • [-] Broken links and cycles (deferred as not needed for demo quality)
  • Integration with test fixtures
    • Playground shares code with Task 6 fixture library
    • Playground templates can be used as regression fixtures (stored in repos/)
    • Maintain DRY principle - single source for demo content
  • Documentation
    • Add playground section to README
    • Document how to reset and regenerate
    • Explain demo project structure (in PLAYGROUND_GUIDE.md)
    • Provide example command workflows

Success Criteria

  • βœ… Playground initializes in <5 seconds (typically <1 second)
  • βœ… Demo project feels realistic and engaging (authentic game dev content)
  • βœ… All Lash features are represented (dependencies, labels, statuses, annotations)
  • βœ… CLI works seamlessly with playground data (TUI pending TUI completion)
  • βœ… Easy to reset and experiment without fear (--reset flag implemented)
  • βœ… Useful for demos, tutorials, and manual exploration (comprehensive PLAYGROUND_GUIDE.md)

Tests

  • βœ… Unit: Playground generation functions (test_pixelquest_generator.rs)
  • βœ… Integration: lash playground init creates valid project (13 integration tests)
  • βœ… E2E: Full workflow (init β†’ index β†’ CLI commands) - 1 comprehensive E2E test
  • βœ… Verify all generated files pass lash lint (integration test)
  • βœ… Verify lash index succeeds on playground (integration test)
  • βœ… Verify lash graph produces valid DOT output (integration test)

Example Usage

# Initialize playground in current directory
lash playground init

# Or specify a path
lash playground init --path ~/lash-demo

# Explore with CLI
cd ~/lash-demo
lash list --label art
lash search "boss fight"
lash show features/boss-fights.md#final-boss
lash graph --output game-systems.dot

# Explore with TUI
lash tui

# Reset to fresh state
lash playground init --reset

Non-Goals (for v1)

  • Property-based testing (fuzzing) - defer to v2
  • Mutation testing - defer to v2
  • Stress testing (>10k files) - manual only
  • Performance regression tracking dashboard - basic reporting only

Open Questions

  • Test parallelism: Run tests in parallel by default or serial?
  • Snapshot review: Automate or manual review?
  • Benchmark CI: Run on every PR or nightly only?
  • MSRV: What's the minimum supported Rust version?

References