zudo-doc
GitHub repository

Type to search...

to open search from anywhere

Generator CLI Testing

CreatedApr 27, 2026Takeshi Takatsudo

How to test the create-zudo-doc generator CLI with Claude Code skills.

Generator CLI Testing

The create-zudo-doc generator CLI scaffolds new zudo-doc projects with various feature combinations. Testing it requires verifying that each combination builds, runs, and produces the correct files and settings.

Two Claude Code skills automate this workflow:

SkillPurpose
/l-generator-cli-tester <pattern>Test a single generation pattern
/l-run-generator-cli-whole-testRun all 9 patterns, fix bugs, verify everything passes

Test Patterns

Each pattern enables a different feature combination:

PatternDescription
bareboneEverything OFF — minimal project
searchOnly search enabled
i18nOnly i18n enabled
sidebar-filterOnly sidebar filter enabled
claude-resourcesOnly Claude Resources enabled
design-token-panelOnly design token panel enabled (uses API)
light-darkLight-dark color scheme mode
lang-jaJapanese as default language
all-featuresEverything ON

Running Tests

Full test suite

Run all 9 patterns end-to-end, automatically fix any failures, and verify:

/l-run-generator-cli-whole-test

With headless browser rendering checks:

/l-run-generator-cli-whole-test --headless

Single pattern

Test one pattern in isolation:

/l-generator-cli-tester barebone
/l-generator-cli-tester all-features --headless

What Each Test Checks

Each pattern goes through these steps:

  1. Scaffold — Run the generator CLI (or programmatic API) with pattern-specific flags
  2. Install — pnpm install in the generated project
  3. Build — pnpm build to verify static export succeeds
  4. Dev server — Start pnpm dev, wait 8 seconds, verify the process is still running
  5. File verification — Check expected files are present/absent based on enabled features
  6. Settings verification — Read the generated settings.ts and confirm correct values
  7. Showcase comparison — Compare generated code against the main zudo-doc showcase
  8. Headless browser (with --headless) — Render pages in a real browser, check for JS errors, verify visual elements (search icon, language switcher, theme toggle, etc.)

The Bug-Fix Workflow

The /l-run-generator-cli-whole-test skill has a structured bug-fix phase:

  1. Phase 1 — Run all 9 patterns and collect results
  2. Phase 2 — For each failure: diagnose which step failed, read the relevant generator source file, apply a minimal fix, rebuild the CLI and re-test the failing pattern, then commit each fix individually
  3. Phase 3 — Re-run all 9 patterns from scratch to ensure no regressions
  4. Phase 4 — Output a summary report

Common failure categories

FailureLikely causeFix location
Missing module at build timeDependency not in generated package.jsonscaffold.ts — generatePackageJson()
Import not found in astro.configFeature integration not includedastro-config-gen.ts
Type error in settings.tsSettings field missing or wrongsettings-gen.ts
Feature component missingFeature module not copying files or injection anchor mismatchfeatures/*.ts or templates/features/*/files/
Anchor remnant in outputInjection anchor not cleaned upcompose.ts — cleanAnchors()

Key Generator Files

FileRole
packages/create-zudo-doc/src/scaffold.tsOrchestrates pipeline: copy base, generate configs, compose features
packages/create-zudo-doc/src/compose.tsComposition engine: injection system, anchor cleanup, feature resolution
packages/create-zudo-doc/src/features/*.tsFeature modules defining injections for each optional feature
packages/create-zudo-doc/src/astro-config-gen.tsProgrammatic astro.config.ts generator
packages/create-zudo-doc/src/content-config-gen.tsProgrammatic content.config.ts generator
packages/create-zudo-doc/src/settings-gen.tsGenerates settings.ts
packages/create-zudo-doc/src/constants.tsFeature definitions, color scheme lists
packages/create-zudo-doc/src/cli.tsCLI argument parsing
packages/create-zudo-doc/src/api.tsProgrammatic API

Notes

  • Test directories are created under __inbox/ (gitignored) to avoid polluting the repo
  • The barebone pattern is the baseline — if it fails, fix it before testing others
  • designTokenPanel is exposed as the --design-token-panel CLI flag, but patterns like design-token-panel and all-features drive it through the programmatic API for consistency with the other test patterns
  • The --headless flag adds browser-level rendering checks on top of process-level checks
  • Always rebuild the CLI (pnpm build in packages/create-zudo-doc) before testing and after each fix
View source on GitHub

Revision History

AI Assistant

Ask a question about the documentation.