Generator CLI Testing

Created Mar 20, 2026Updated Jul 10, 2026Takeshi Takatsudo

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

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

Two Claude Code skills automate this workflow:

Skill	Purpose
`/l-generator-cli-tester <pattern>`	Test a single generation pattern
`/l-run-generator-cli-whole-test`	Run all 9 patterns, fix bugs, verify everything passes

Test Patterns

Each pattern enables a different feature combination:

Pattern	Description
`barebone`	Everything OFF — minimal project
`search`	Only search enabled
`i18n`	Only i18n enabled
`sidebar-filter`	Only sidebar filter enabled
`claude-resources`	Only Claude Resources enabled
`design-token-panel`	Only design token panel enabled (uses API)
`light-dark`	Light-dark color scheme mode
`lang-ja`	Japanese as default language
`all-features`	Everything 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:

Scaffold — Run the generator CLI (or programmatic API) with pattern-specific flags
Install — pnpm install in the generated project
Build — pnpm build to verify static export succeeds
Dev server — Start pnpm dev, wait 8 seconds, verify the process is still running
File verification — Check expected files are present/absent based on enabled features
Config verification — Read the generated zfb.config.ts and confirm the zudoDoc({ … }) call holds the expected fields (diff-from-defaults; there is no separate settings.ts)
Showcase comparison — Compare generated code against the main zudo-doc showcase
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:

Phase 1 — Run all 9 patterns and collect results
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
Phase 3 — Re-run all 9 patterns from scratch to ensure no regressions
Phase 4 — Output a summary report

Common failure categories

Failure	Likely cause	Fix location
Missing module at build time	Dependency not in generated `package.json`	`scaffold.ts` — `generatePackageJson()`
Wrong/missing field in `zfb.config.ts`	`zudoDoc()` diff-from-defaults emitted incorrectly	`zfb-config-gen.ts`
Type error in generated config	Field mismatched against `ZudoDocConfig`	`zfb-config-gen.ts`
Feature file missing	Feature module not copying files (only the few features that still ship files)	`features/.ts` or `templates/features//files/`
Anchor remnant in output	Injection anchor not cleaned up (`ANCHOR_FILES` is now empty)	`compose.ts` — `cleanAnchors()`

Key Generator Files

File	Role
`packages/create-zudo-doc/src/scaffold.ts`	Orchestrates pipeline: copy base, generate config, compose features
`packages/create-zudo-doc/src/compose.ts`	Composition engine: injection system, anchor cleanup, feature resolution
`packages/create-zudo-doc/src/features/*.ts`	Feature modules — mostly settings-field emission now; only a few still copy files
`packages/create-zudo-doc/src/zfb-config-gen.ts`	The single config generator — emits `zfb.config.ts` as a `zudoDoc({ … })` diff-from-defaults call (the former `settings-gen.ts` is gone)
`packages/create-zudo-doc/src/preset.ts`	Feature-preset resolution shared across CLI and API
`packages/create-zudo-doc/src/claude-md-gen.ts`	Generates the project `CLAUDE.md` for the new project shape
`packages/create-zudo-doc/src/constants.ts`	Feature definitions, color scheme lists
`packages/create-zudo-doc/src/cli.ts`	CLI argument parsing
`packages/create-zudo-doc/src/api.ts`	Programmatic 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