| name | test-volo-flow |
| description | Tests the create-volo-app CLI end-to-end against a local volo-app template. Use when validating CLI or template changes, running scaffold smoke tests, checking validateTemplate requirements, or verifying volo-config.json flows. |
| disable-model-invocation | true |
Test Volo Flow
End-to-end smoke test for create-volo-app using a local volo-app template.
Prerequisites: Open the create-volo-app repository as the workspace (or ensure the shell cwd is its root).
Use required_permissions: ["all"].
Shell commands
Run every command from the create-volo-app repository root. Do not prefix commands with cd … && — that triggers extra approval and is unnecessary. Set the shell tool's working_directory to the repo root instead.
Fixed paths (nothing else is touched)
| Path | Purpose |
|---|
.tmp/volo-flow-test | Scaffolded test project |
.tmp/volo-flow-test.state.json | Run metadata (includes dev pid and frontend URL after dev) |
.tmp/volo-flow-test.dev.log | Captured stdout/stderr from test:volo-flow:dev (for debugging API/service failures) |
Template default: ../volo-app (override with VOLO_APP_TEMPLATE).
1. Run scaffold + verification
pnpm test:volo-flow
Steps (each prints OK or FAILED):
- Check test dir (refuses to overwrite unless
--force)
- Check pnpm
- Build CLI
- Scaffold test project
- Verify scaffold structure
- Verify builds
On failure: prints a summary, leaves .tmp/volo-flow-test in place for inspection.
Replace an existing test dir:
pnpm test:volo-flow -- --force
2. Start dev server
pnpm test:volo-flow:dev
Starts the scaffolded app in the background with VOLO_DEV_IGNORE_STDIN=1, waits for VOLO_DEV_FRONTEND_URL=… and VOLO_DEV_BACKEND_URL=… from scripts/run-dev.js, verifies backend GET / health, captures all service output to .tmp/volo-flow-test.dev.log, writes URLs and dev pid to state, then exits while services keep running.
On failure (timeout, process exit, or backend health check), prints a filtered excerpt from the dev log before exiting non-zero.
3. Browser verification (AI)
- Open the frontend URL from the dev command output or state file.
- Confirm Welcome to Your App!
- Optionally confirm the auth UI renders. Full sign-in is not required.
4. Stop dev server and cleanup
pnpm test:volo-flow:stop
pnpm test:volo-flow:cleanup
stop sends SIGINT to the pid recorded in state and waits for shutdown. cleanup stops the dev server if needed, then deletes only .tmp/volo-flow-test and .tmp/volo-flow-test.state.json.
validateTemplate() requirements
These files must exist in the template. Do not remove or rename them without updating src/utils/template.ts:
package.json (must include template.placeholders)server/src/api.tsserver/src/trpc/router.tsserver/src/server.tsserver/src/lib/env.tsserver/.env.exampleserver/platforms/cloudflare/wrangler.toml.templateui/platforms/cloudflare/wrangler.toml.templateui/src/lib/firebase-config.template.jsonscripts/post-setup.jsscripts/run-dev.jsscripts/deploy-guard.jsscripts/parse-wrangler-deploy-url.jsserver/package.json (must include dev, deploy, deploy:cf scripts)
Local template copy excludes: node_modules/, .git/, dist/, .next/, data/.
Dev readiness log contract
pnpm test:volo-flow:dev parses stdout from the scaffolded app’s pnpm run dev → volo-app scripts/run-dev.js.
Required machine-readable lines (do not rename without updating scripts/test-volo-flow.mjs):
VOLO_DEV_FRONTEND_URL=http://localhost:5501
VOLO_DEV_BACKEND_URL=http://localhost:5500
After both URLs appear, the runner polls GET {backendUrl}/ until { "status": "ok" } or times out (30s).
All dev stdout/stderr during startup is appended to .tmp/volo-flow-test.dev.log. On startup/health failure, the runner prints a filtered excerpt (lines tagged [server], [database], errors, etc.) plus the full log path. After dev-ready, the runner exits (dev server keeps running in the background); the log file retains startup output only.
Legacy fallbacks: human Frontend: / Backend: lines for older templates.
