---
roadcrew_template_name: "start-testing.md"
roadcrew_template_type: "command"
roadcrew_template_version: "v1.0"
roadcrew_last_updated: "2025-10-25"
roadcrew_min_version: "1.5.0"
roadcrew_license: "See LICENSE file in .roadcrew folder"
roadcrew_copyright: "Copyright (c) 2025 North Star Holdings, LLC"
spdx_license_identifier: "LicenseRef-RoadcrewLicense-1.0"
execution_mode: "auto-execute"
---

# start-testing

Set up testing environment and run your first test. TDD-focused with interactive guidance.

> **Execution:** Runs immediately with automatic test setup. No approval pauses.

**Cost Optimization:** Script-first approach - validates existing tests before generating new ones.

<!-- Usage: /start-testing [--repo https://github.com/org/repo] -->

You are running the automated testing workflow for a completed epic implementation.

**PREREQUISITE:** User must have completed `/implement-epic` first. This command assumes all code is implemented and EPIC-XXX-TEST-PLAN.md exists.

**Standalone Mode Support:** If --repo flag provided, use that repo for testing and look for config in config/repos/org-repo/. If no --repo flag, use current repo (integrated mode).

MANDATORY CURSORRULES COMPLIANCE: Reference @.cursorrules.md throughout this work.

## WORKFLOW:

### 0. PRE-FLIGHT CHECKS
- Review @.cursorrules.md (workflow preferences, branch strategy)
- Review @memory-bank/techContext.md (project context, deployment, testing)
- Locate test plan file:
  * Check repo root: EPIC-XXX-TEST-PLAN.md
  * Check tests/ directory: tests/EPIC-XXX-TEST-PLAN.md
  * Check docs/ directory: docs/testing/EPIC-XXX-TEST-PLAN.md
  * Ask user if not found in standard locations
- Extract epic number from filename
- Verify current branch matches epic branch format:
  * Roadcrew: `epic-{NUMBER}` (from dev)
  * Typical projects: `epic-{NUMBER}` (from main/master)
  * Detected from memory-bank/techContext.md or .cursorrules.md
- Count total number of tests in plan

### 0.5 ENVIRONMENT DETECTION & DISPLAY

Detect and display testing environment context from memory-bank/techContext.md:
```
🔍 Testing Environment:
- Project Type: [Node.js/Python/Library/CLI Tool/Web App]
- Deployment: [GitHub Actions/Vercel/Docker/Manual/None]
- Test Framework: [Jest/Playwright/pytest/Go test/None]
- Base Branch: [dev/main/master]
- Current Branch: [epic-{NUMBER}]
- Schema Changes: [Yes/No - if Prisma detected]
- Breaking Changes: [Yes/No - from test plan metadata]
```

This context helps user understand what to expect during testing.

### 1. DEPLOYMENT (Detection-Based from memory-bank/techContext.md)

**Schema Changes First (if detected):**
- If Prisma/schema changes detected:
  * Run migrations: `npx prisma migrate dev` or project-specific
  * Verify schema changes applied
  * Test rollback works if needed
  * Confirm before proceeding

**Deployment by Type:**

**GitHub Actions:**
- Push current branch to trigger workflows
- Display Actions URL: `https://github.com/owner/repo/actions`
- Monitor workflow status
- Wait for deployment to complete
- Show deployment URL from workflow output

**Vercel:**
- Deploy via `git push` or `vercel deploy`
- Display Preview URL: `https://project-abc123.vercel.app`
- Display Dashboard: `https://vercel.com/owner/project`
- Wait for deployment ready status

**Docker:**
- Run: `docker-compose up --build` or project-specific
- Display container status: `docker ps | grep project-name`
- Display local URL: `http://localhost:8080` (or configured port)
- Verify containers healthy

**Local Development:**
- Start dev server: `npm run dev` / `yarn dev` / project-specific
- Display local URL: `http://localhost:3000` (or configured port)
- Note: Keep terminal running during testing
- Verify app loads without errors

**Manual Deployment:**
- Display project-specific deployment instructions
- Wait for user confirmation of deployment
- Ask for deployed URL(s)

**None/Library/Package:**
- Build package: `npm run build` / `python setup.py build` / project-specific
- Display build output location: `./dist/` or `./build/`
- For libraries: Show test import command
- Skip deployment, proceed to testing

- Confirm deployment successful before proceeding to tests

### 1.5 PRE-TESTING SETUP (Project-Type Specific)

**Web Apps:**
- Verify development server running
- Open app in browser at displayed URL
- Check browser console for errors
- Verify initial page load successful
- Confirm hot reload working (if applicable)

**Libraries/Packages:**
- Verify build completed successfully
- Install locally for testing: `npm link` / `pip install -e .`
- Create test project or use existing one
- Verify import works: Show import statement
- Check public API accessible

**CLI Tools:**
- Verify build completed: `npm run build` / `go build`
- Make executable: `chmod +x [binary]` (if needed)
- Add to PATH or note full path for testing
- Test help flag: `./tool --help` or `tool --help`
- Verify version displays correctly

**Platform Mode (Roadcrew):**
- Verify detection utilities can run
- Check test projects available for validation
- Confirm command files accessible to Cursor
- Prepare isolated directory for template testing
- Verify config files present and valid

### 1.6 AUTOMATED TESTS (if test framework detected)

**Before manual testing, run automated test suite:**

**Node.js Projects:**
- Run: `npm test` or `npm run test:epic-{NUMBER}` (if epic-specific tests exist)
- Display test results (passed/failed/skipped)
- Show coverage report if available
- If failures: Offer to fix before manual testing
- If passing: Proceed to manual acceptance tests

**Python Projects:**
- Run: `pytest` or `pytest tests/epic_{NUMBER}/` (if epic-specific tests exist)
- Display test results with verbose output
- Show coverage report if configured
- If failures: Offer to fix before manual testing
- If passing: Proceed to manual acceptance tests

**Go Projects:**
- Run: `go test ./...` or `go test -v ./pkg/epic{NUMBER}/`
- Display test results
- Show coverage: `go test -cover ./...` (if configured)
- If failures: Offer to fix before manual testing
- If passing: Proceed to manual acceptance tests

**Other Test Frameworks:**
- Detect and run project-specific test command
- Display results in standard format
- If failures: Offer to fix before manual testing
- If passing: Proceed to manual acceptance tests

**No Automated Tests:**
- Note: No automated tests detected
- All testing will be manual
- Proceed directly to manual test execution

**Hybrid Approach (Most Common):**
- Run automated tests first (unit/integration)
- Display automated test results
- Then proceed to manual acceptance tests
- Manual tests focus on user-facing behavior and UX

### 2. MANUAL TEST EXECUTION LOOP
For each manual test in the test plan:

**Test Presentation Format:**
```
Test {NUMBER}: {TITLE}

Steps:
1. {ACTION VERB} {rest of step}
2. {ACTION VERB} {rest of step}
3. {ACTION VERB} {rest of step}

Expected Results:
1. {Expected outcome}
2. {Expected outcome}
3. {Expected outcome}

Done or did you find something?
```

**User Response Handling:**
- If user responds "Done":
  * Mark test as ✅ PASSED
  * Immediately move to next test
  * NO additional commentary between tests
  
- If user reports an issue:
  * Document the issue details
  * Ask clarifying questions if needed
  * Fix the code
  * Ask: "Ready to retry this test or continue?"
  * If retry: re-present same test
  * If continue: mark as ⚠️ ISSUE FOUND, move to next test

### 3. COMPLETION & NEXT STEPS

After all tests executed:
- Display summary:
  ```
  🎉 Testing Complete!
  
  Automated Tests:
  ✅ Passed: {count}
  ❌ Failed: {count}
  ⏭️  Skipped: {count}
  
  Manual Tests:
  ✅ Passed: {count}
  ⚠️ Issues Found: {count}
  
  Total Tests: {count}
  Coverage: {X%} (if measurable)
  ```

**All Tests Passed - Offer Next Actions:**

A. **Create PR** (most common)
   - Create PR from epic-{NUMBER} → base branch (dev/main)
   - Include test results in PR description
   - Tag appropriately (enhancement, breaking-change, etc.)

B. **Tag Release** (if version bump needed)
   - Update version in package.json / __version__ / etc.
   - Create git tag: v{X.Y.Z}
   - Generate release notes from commits

C. **Deploy to Production** (if deployment configured and approved)
   - Follow project-specific production deployment
   - Monitor deployment status
   - Verify production health checks

D. **Update Documentation** (if breaking changes)
   - Update README with breaking changes
   - Update migration guide
   - Update CHANGELOG

**Issues Found - Offer Actions:**

A. **Create GitHub Issues** for each problem
   - One issue per distinct problem found
   - Include test steps that revealed issue
   - Link to epic for context
   - Label appropriately

B. **Fix Issues Now** and retry tests
   - Fix problems immediately
   - Commit fixes to epic branch
   - Re-run affected tests
   - Continue when fixed

C. **Mark as Known Issues** and continue
   - Document issues in test plan
   - Note as "known limitation" or "future enhancement"
   - Proceed with PR noting issues

D. **Cancel and Return** to implementation
   - Major issues found requiring redesign
   - Return to /implement-epic workflow
   - Preserve test results for reference

**Schema Changes Detected - Additional Reminders:**
- Verify migration documentation complete
- Confirm rollback plan documented and tested
- Check migration tested in both directions (up/down)
- Ensure data backups discussed if production migration

## TEST PLAN PARSING RULES:

1. **Test Identification:**
   - Tests are numbered like "Test 1.1:", "Test 2.3:", etc.
   - Extract test number and title
   - Find steps section (starts with "Steps:")
   - Find expected results section (starts with "Expected Results:")

2. **Step Extraction:**
   - Steps are numbered lists under "Steps:" header
   - Each step should start with action verb (Open, Run, Change, Click, Verify, etc.)
   - Keep steps as-is from test plan, don't reformat

3. **Expected Results Extraction:**
   - Expected results are numbered/bulleted lists under "Expected Results:" header
   - Preserve checkboxes (✅) and formatting from test plan

4. **Test Boundaries:**
   - Test ends when next "Test X.Y:" header found OR next major section (###, ##)
   - Ignore verbose explanatory text between tests - focus on structured test content

## AUTOMATION GUIDELINES:

1. **Be Efficient:**
   - No unnecessary explanations between tests
   - Just present test → wait for response → move to next
   - User is busy, respect their time

2. **Be Clear:**
   - Present test exactly as formatted in test plan
   - Keep steps and expected results intact
   - Don't add extra commentary

3. **Be Responsive:**
   - If user finds issue, prioritize fixing it
   - Don't force them through all tests if critical issue found
   - Offer to skip remaining tests if major problem discovered

4. **Track Progress:**
   - Maintain internal count of current test position
   - Show progress indicator: "Test 3 of 21"
   - Update test plan file with pass/fail status after each test

## EXAMPLE FLOW (Web App):

```
🚀 Starting automated testing for Epic #224

Found test plan: EPIC-224-TEST-PLAN.md
Total tests: 15 (8 automated + 7 manual)
Branch: epic-224

🔍 Testing Environment:
- Project Type: Next.js Web App
- Deployment: Vercel
- Test Framework: Jest + Playwright
- Base Branch: main
- Current Branch: epic-224
- Schema Changes: Yes (Prisma)
- Breaking Changes: No

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Running schema migrations...
✅ Prisma migrations applied successfully

Deploying to Vercel...
✅ Deployment complete
   Preview URL: https://project-abc123.vercel.app
   Dashboard: https://vercel.com/owner/project

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Running automated tests...

npm test
✅ 47 tests passed
❌ 1 test failed: "User authentication redirects correctly"
⏭️  2 tests skipped

Fixing failed test...
[fixes authentication redirect issue]
Re-running tests...
✅ All 48 tests passed

Test Coverage: 87% (+5% from baseline)

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Proceeding to manual acceptance tests...

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Manual Test 1 of 7

Test 1.1: User Dashboard Loads

Steps:
1. Open https://project-abc123.vercel.app/dashboard
2. Log in with test credentials (test@example.com / password123)
3. Verify dashboard displays user name
4. Check for console errors in browser DevTools

Expected Results:
1. Login successful within 2 seconds
2. Dashboard shows "Welcome, Test User"
3. No console errors or warnings
4. All widgets load properly

Done or did you find something?
```

**User:** "Done"

```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Manual Test 2 of 7

Test 1.2: Create New Project

Steps:
1. Click "New Project" button
2. Fill in project name: "Test Project Alpha"
3. Select project type: "Web Development"
4. Click "Create"

Expected Results:
1. Form validates correctly
2. Project created and appears in project list
3. User redirected to project detail page
4. Success message displays

Done or did you find something?
```

**User:** "The success message doesn't display"

```
Got it - investigating the success message logic...

[fixes notification component]

Ready to retry this test or continue?
```

## BEHAVIOR:

- If invoked without epic context, search for most recent EPIC-XXX-TEST-PLAN.md file
- If multiple test plans found, ask user which epic to test
- Start testing immediately after user confirms (don't wait for additional approval)
- Maintain test state across conversation - can pause and resume
- Save progress to test plan file after each test