Manual Testing Plan#

Step through this checklist to validate the complete user journey.

Prerequisites#

Node.js >=20.9.0 installed (tested on v25.2.1)
pnpm installed globally (tested on v10.x)
Clean test directory (~/Code/tests/test-scaffold)

1. CLI Invocation#

1.1 With project name argument#

cd ~/Code/tests/test-scaffold
node /path/to/bin/mcp-app-studio.js my-app

Intro banner shows mcp-app-studio
Spinner shows "Creating project..." (implicit, fast)
Success message "Project created!"
"Next steps" box shows correct commands
Export hint displayed at end

Notes: Banner displays correctly, all steps shown. Uses npm commands when run with node directly.

1.2 Interactive mode (no argument)#

Prompts for project name (requires TTY)
Accepts valid name (requires TTY)
Rejects invalid names with error message (requires TTY)
Cancel with Ctrl+C exits cleanly (requires TTY)

Notes: Skipped - requires interactive TTY input.

1.3 Overwrite existing directory#

Prompts "Directory is not empty. Remove existing files?" (requires TTY)
Selecting "No" cancels without deleting (requires TTY)
Selecting "Yes" removes contents and scaffolds (requires TTY)

Notes: Skipped - requires interactive TTY input.

1.4 Empty directory with .git#

Does NOT prompt to overwrite (treats as empty)
Scaffolds successfully

Notes: Works correctly. Directory with only .git is treated as empty.

1.5 Template selection#

--template minimal generates only the Welcome example + wrapper
--template poi-map generates only the POI Map example + wrapper
mcp-app-studio.config.json defaults match the selected template:
- minimal → lib/workbench/wrappers/welcome-card-sdk.tsx / WelcomeCardSDK
- poi-map → lib/workbench/wrappers/poi-map-sdk.tsx / POIMapSDK

1.6 Server toggle#

--include-server includes server/ (default behavior)
--no-server does not create server/ and does not attempt server postinstall

2. Scaffolded Project Structure#

2.1 Essential files exist#

Notes: All files present. Uses PostCSS config for Tailwind v4.

2.2 Directories exist#

app/
components/
lib/
scripts/

2.3 package.json contents#

name matches project name (sanitized) → "my-app"
version is 0.1.0
private is true
Has scripts.dev → "tsx scripts/dev.ts"
Has scripts.dev:next → "next dev -p 3002"
Has scripts.build → "next build"
Has scripts.export → "tsx scripts/export.ts"

For --template poi-map: components/examples/poi-map/ directory exists
For --template poi-map: contains index.tsx, schema.ts, poi-map.tsx
For --template minimal: components/examples/welcome-card/ directory exists
For --template minimal: contains index.tsx, schema.ts, welcome-card.tsx

3. Development Flow#

3.1 Install dependencies#

Completes without errors (5.6s, 637 packages)
node_modules/ created
No blocking peer dependency warnings
If server included: server/node_modules/ auto-created via postinstall
If server included: @modelcontextprotocol/sdk installed in server

Notes: Warning about ignored build scripts (esbuild, sharp) is expected and non-blocking. npm audit warnings may appear depending on your environment.

3.2 Start dev server#

Next.js starts (default: http://localhost:3002)
MCP server starts (default: http://localhost:3001/mcp, auto-selects a free port if 3001 is in use)
No console errors on startup
Ready in 1218ms with Turbopack

Notes: The root dev script starts both Next.js and the MCP server (when included). The MCP server port is printed on startup and written to server/.mcp-port for tooling.

3.3-3.5 Workbench UI & POI Map#

(Skipped - requires browser automation)

Notes: Page title confirmed: "Create ChatGPT App"

3.6 MCP Server (when included)#

Notes: cd server && npm run inspect reads PORT if set; otherwise it uses server/.mcp-port written by the running server.

4. Build Flow#

4.1 Production build#

Completes without errors (2.4s)
.next/ directory created
No TypeScript errors in output
No Lint errors in output

Notes: 5 routes generated (2 static, 2 dynamic API routes).

4.2 Start production server#

(Not tested - requires long-running server)

5. Export Flow#

5.1 Run export#

Completes without errors
export/ directory created

5.2 Export contents#

export/manifest.json exists
export/widget/widget.js exists
export/widget/index.html exists
export/widget/widget.css exists
export/README.md exists
If using POI Map template: export/widget/assets/ contains required Leaflet assets

5.3 Manifest validation#

Valid JSON
Contains: schema_version, name, widget.url, version
Contains recommended: description
Widget URL placeholder present for deployment

Contains bundled JavaScript (React 19.2.3)
No source map references to local paths
Minified production build

6. Package Manager Detection#

6.1 With pnpm#

(Requires pnpm dlx)

6.2 With npm#

"Next steps" shows npm install and npm run dev

6.3 With yarn#

(Requires yarn)

7. Name Sanitization#

Input	Expected	Actual	Status
`my app`	`my-app`	`my-app`	✅
`MyApp`	`myapp`	`myapp`	✅
`.hidden`	`hidden`	`hidden`	✅
`_private`	`private`	`private`	✅

Each tested input produces expected sanitized name

Notes: Directory keeps original name; package.json name is sanitized.

8. Error Scenarios#

8.1-8.2 Interactive errors#

(Requires TTY)

8.3 Port already in use#

MCP server avoids port conflicts by selecting the next available port
If Next.js port (3002) is already in use, verify it either auto-selects a new port or exits with a clear message

8.4 Missing .env.local values#

App starts without API keys
Workbench works for mocking

9. Edge Cases#

9.1 Very long project name#

Creates successfully with 60-character name

9.2 Unicode in project name#

(Not tested)

9.3 Current directory scaffold#

Scaffolds in current directory
Uses directory name for package name (test-current-dir)

Notes: This was previously broken (empty package name). Now fixed!

10. Cleanup#

rm -rf ~/Code/tests/test-scaffold/*

Issues Found#

Step	Issue	Severity	Status
2.1	Test plan incorrectly expected `.env.local` to be scaffolded	Low	FIXED (docs)
9.3	Scaffold with `.` set empty package name	Low	FIXED
3.1	Server deps not auto-installed (required manual `cd server && npm install`)	High	FIXED
3.2	`appComponent` import doesn't exist in generated `component-registry.tsx`	Critical	FIXED
3.2	Peer dependency mismatch between assistant-ui packages	High	FIXED
3.6	MCP server crashes on `EADDRINUSE` (port 3001)	Medium	FIXED (starter repo)
3.6	`cd server && npm run inspect` hardcoded port 3001	Low	FIXED (starter repo)
3.6	Stopping `npm run dev` left child processes on ports 3002 / 300x	High	FIXED (starter repo)
5.3	Export manifest missing recommended `description` field	Low	FIXED (starter repo)

Sign-off#

All critical paths tested
No blocking issues found
Ready for release

Tested by:
Date: YYYY-MM-DD

Skipped tests#

Skipped tests usually require:

Interactive TTY input (prompts, Ctrl+C)
Browser validation (workbench UI)
Specific package managers (yarn, pnpm dlx)