Test Feature Locally

Test a feature on a local web application using Muggle AI local MCP tools.

Workflow Overview

Login (required) → Authenticate with Muggle AI
      ↓
List Sources (merged) → Present unified local+cloud projects
      ↓
Select Project → User chooses project
      ↓
Sync Local Copy → Pull latest from cloud if both exist
      ↓
Analyze Changes (optional) → Identify impacted features
      ↓
List Use Cases → Find/Create/Pull Use Case(s)
      ↓
List Test Cases → Find/Create/Pull Test Case(s)
      ↓
List Test Scripts → Generate (if none) or Replay (if exists)

Prerequisites

• Local MCP server running
• Target web application running (e.g., http://localhost:3999)
• User describes the feature to test OR has code changes to analyze

Mandatory Result Format (Paths + IDs)

For every Local MCP tool result you report to the user, include:

1. Result: concise summary of pass/fail or key output
2. Local File Path(s): paths returned by MCP output
3. IDs: relevant IDs (project/use case/test case/test script/run)
4. Path Availability:
   • If MCP returns path(s): mark as reported
   • If path(s) are computed from IDs/input: mark as derived
   • If no path can be obtained: explicitly state path not exposed by MCP output

Never omit this section when presenting Local MCP output.

Hard-Fail Policy (No Browser Fallback)

This skill is Local MCP only. If Local MCP tools are unavailable or a required Local MCP step fails, stop and fail this workflow.

Do not fall back to generic browser testing features/tools to continue execution.

When failing, clearly report:

1. Which Local MCP step/tool failed
2. The error message
3. What user action is needed (for example, start Local MCP, fix auth, or run local app)

Step 0: Login (Required)

Always start by ensuring the user is authenticated. This is mandatory before any testing can begin.

Check Authentication Status

Call muggle_auth_status to check if user is already logged in.

If Not Authenticated

1. Inform user: "You need to log in to Muggle AI to start testing."
2. Call muggle_auth_login to initiate the login flow
3. Wait for authentication to complete
4. Confirm: "Logged in as [email]. Ready to proceed."

If Already Authenticated

Confirm: "Already logged in as [email]. Let's continue."

Important: Do NOT proceed to any other steps until authentication is confirmed.

Step 1: List All Sources (Local + Cloud)

Always present both local and cloud projects for the user to choose from, with matching projects merged.

List Both Sources

1. Call muggle_project_list to see existing local projects
2. Call muggle_cloud_project_list to list cloud projects

Merge Matching Projects

Projects are considered matching when:

• Local project has cloudSource.projectId matching a cloud project ID
• OR local project name matches cloud project name (case-insensitive)

Present Unified List

Present projects in a merged format - matching local/cloud projects appear as ONE entry:

Logged in as: user@example.com

PROJECTS:
| # | Name | Local | Cloud | Local URL |
|---|------|-------|-------|-----------|
| 1 | MuggleTest Staging | Yes | Yes | http://localhost:3999 |
| 2 | Admin Portal | No | Yes | - |
| 3 | My Local App | Yes | No | http://localhost:3000 |

Options:
  - Enter a number to use that project
  - Type "new" to create a new project

Column meanings:

• Local: "Yes" if local copy exists
• Cloud: "Yes" if cloud version exists
• Local URL: The localhost URL for testing (or "-" if needs to be set)

User Selection Logic

Selection	Local?	Cloud?	Action
Number	Yes	Yes	Sync first: Pull latest from cloud, then use local
Number	Yes	No	Use existing local project
Number	No	Yes	Prompt for localhost URL, pull to local
"new"	-	-	Create new local project

Sync Before Testing (Critical)

When a project has both local AND cloud versions, always sync before testing:

1. Inform user: "Syncing local copy with cloud..."
2. Call muggle_cloud_pull_project with the cloud project ID and existing local URL
3. This updates use cases and test cases to match cloud
4. Confirm: "Local copy synced. Ready to test."

Important: Always wait for user to select a project before proceeding.

Step 2: Analyze Current Changes (Optional but Recommended)

When user asks to "test my changes" or doesn't specify a feature, analyze the codebase changes first.

Gather Change Context

Run these commands to understand what changed:

git status
git diff
git diff --cached
git log -3 --oneline

Identify Impacted Features

From the changes, extract:

1. Modified components/pages: Which UI components or pages changed?
2. Modified API endpoints: Which backend routes are affected?
3. Modified services/logic: What business logic changed?

Map Changes to Test Areas

Change Type	Likely Impacted Tests
Login/auth files	Authentication use cases
User profile files	User management use cases
Form components	Data input/validation test cases
API route handlers	CRUD operation test cases
Navigation/routing	Navigation flow use cases
Payment/checkout	Transaction test cases

Present Findings to User

After analysis, summarize:

1. What files changed
2. What features are likely impacted
3. Suggested use cases/test cases to run

Example output:

Based on your changes:
- Modified: src/components/LoginForm.tsx, src/api/auth.ts
- Impacted features: User authentication, session management
- Suggested tests:
  1. "User can log in with valid credentials"
  2. "User sees error with invalid password"
  3. "User can reset password"

Which test(s) would you like to run?

Step 3: Pull from Cloud (If Selected)

When user selects a cloud project, use case, or test case:

Prompt for Local Testing URL

You selected a cloud project with URL: https://app.example.com

What localhost URL should be used for local testing?
(e.g., http://localhost:3000, http://localhost:3999)

Pull and Rewrite URL

Call muggle_cloud_pull_project with:

{
  "cloudProjectId": "<cloud_project_id>",
  "localUrl": "<user_provided_localhost_url>"
}

What happens:

1. Downloads project metadata from cloud
2. Stores originalUrl field with the cloud URL (e.g., https://app.example.com)
3. Rewrites url field to localhost URL (e.g., http://localhost:3000)
4. Creates local copies of use cases and test cases with same URL rewriting
5. Tracks cloudSource mapping for future sync

URL Rewriting Rules

Field	Original (Cloud)	Rewritten (Local)
project.url	https://app.example.com	http://localhost:3000
project.originalUrl	(none)	https://app.example.com
testCase.url	https://app.example.com/login	http://localhost:3000/login
testCase.originalUrl	(none)	https://app.example.com/login

Path preservation: When rewriting URLs, preserve the path portion:

• https://app.example.com/dashboard → http://localhost:3000/dashboard
• https://app.example.com/users/123 → http://localhost:3000/users/123

Step 4: Identify or Create Project

If not pulling from cloud, find or create a local project.

Call muggle_project_list to see existing projects.

Match logic:

• Match by URL (exact or base domain match)
• Match by project name (case-insensitive contains)

If match found: Use existing project, confirm with user.

If no match: Call muggle_project_create with:

• name: Derived from app name or URL
• url: The localhost URL
• description: Brief description of the app

Step 5: Identify or Create Use Case(s)

Call muggle_use_case_list with the projectId.

Match logic:

• Match by goal/title containing key terms from user's feature description
• Match against impacted features from change analysis (Step 0)
• Look for similar user personas

If multiple matches found:

1. List all matching use cases with brief descriptions
2. Ask user: "Found N use cases that may be impacted. Which would you like to test?"
3. Allow selecting multiple (e.g., "all", "1,2,3", or specific names)

If single match found: Confirm with user, use existing.

If no match: Call muggle_use_case_save with:

{
  "projectId": "<projectId>",
  "useCase": {
    "title": "<Feature name>",
    "userStory": "<As a user, I want to...>",
    "description": "<Detailed description>",
    "breakdownItems": [{"stepNumber": 1, "action": "...", "expected": "..."}]
  }
}

Step 6: Identify or Create Test Case(s)

Call muggle_test_case_list with projectId and optionally useCaseId.

Match logic:

• Match by title or goal containing feature keywords
• Match against impacted features from change analysis (Step 0)
• Match by URL if provided
• For each selected use case, find associated test cases

If multiple matches found:

1. List all matching test cases grouped by use case
2. Show which are likely impacted based on change analysis
3. Ask user: "Found N test cases. Run all impacted, or select specific ones?"
4. Options: "all", "impacted only", or specific IDs

Example output:

Found test cases:

Use Case: User Authentication
  [IMPACTED] tc_001 - Login with valid credentials (login form changed)
  [IMPACTED] tc_002 - Login with invalid password
  [ ] tc_003 - Remember me functionality

Use Case: User Profile
  [ ] tc_004 - Update display name

Run: [all impacted] [all] [select specific]?

If single match found: Confirm with user, use existing.

If no match: Call muggle_test_case_save with:

{
  "projectId": "<projectId>",
  "useCaseId": "<useCaseId>",
  "testCase": {
    "title": "<Test case name>",
    "goal": "<What this test verifies>",
    "url": "<Starting URL - use localhost>",
    "precondition": "<Any setup needed>",
    "instructions": "<Step-by-step instructions>",
    "expectedResult": "<What should happen>"
  }
}

Step 7: Generate or Replay Test Script(s)

For each selected test case, call muggle_test_script_list with projectId and testCaseId.

For multiple test cases:

Process each test case and categorize:

Test execution plan:
  REPLAY (script exists):
    - tc_001: Login with valid credentials
    - tc_002: Login with invalid password
  
  GENERATE (no script):
    - tc_005: New password reset flow

Proceed? [yes/no]

If test script exists:

1. Confirm with user: "Found existing test script. Replay it?"
2. If yes, call muggle_execute_replay:

   {
     "projectId": "<projectId>",
     "testScriptId": "<testScriptId>"
   }
   

3. Report results from the execution

If no test script:

1. Inform user: "No test script found. Generating one..."
2. Call muggle_execute_test_generation:

   {
     "projectId": "<projectId>",
     "testCaseId": "<testCaseId>"
   }
   

3. Wait for generation to complete
4. Report the generated script details

Batch Execution Order

When running multiple tests:

1. Replay existing scripts first (faster, validates current behavior)
2. Generate new scripts after (slower, may need user observation)
3. Track results for each test case

Step 8: View Results

After execution, call muggle_run_result_list or muggle_run_result_get to show:

• Pass/fail status
• Screenshots captured
• Execution time
• Any errors encountered

For Multiple Tests - Summary Report

After running multiple tests, provide a summary:

Test Run Summary
================
Total: 4 tests
Passed: 3
Failed: 1

Results:
  [PASS] tc_001 - Login with valid credentials (2.3s)
  [PASS] tc_002 - Login with invalid password (1.8s)
  [FAIL] tc_003 - Remember me functionality (3.1s)
     Error: Checkbox not found on page
  [PASS] tc_005 - Password reset flow (4.2s) [newly generated]

Failed test details:
  tc_003: Element '#remember-me' not found. 
          Screenshot: run_xxx/step_3.png

Suggested Next Actions

Based on results:

Result	Suggested Action
All passed	"All tests passed. Ready to commit?"
Some failed	"N tests failed. Review failures or re-run?"
New scripts generated	"N new scripts created. Replay to verify?"

Example Interactions

Example 1: Test with Existing Synced Project

User: "Test the login feature at localhost:3999"

Agent:

1. muggle_auth_status → Not authenticated
2. muggle_auth_login → User completes login
3. Confirm: "Logged in as user@example.com"
4. muggle_project_list → Found 1 local project (MuggleTest Staging)
5. muggle_cloud_project_list → Found cloud project with same name
6. Present merged list:

   | # | Name | Local | Cloud | Local URL |
   |---|------|-------|-------|-----------|
   | 1 | MuggleTest Staging | Yes | Yes | http://localhost:3999 |
   | 2 | Other App | No | Yes | - |
   

7. User: "1"
8. Sync: "Syncing local copy with cloud..."
9. muggle_cloud_pull_project → Updates local with latest from cloud
10. Confirm: "Local copy synced. Ready to test."
11. muggle_use_case_list → Found "User Authentication"
12. muggle_test_case_list → Found 3 test cases
13. Run tests against localhost:3999

Example 2: Test Based on Code Changes

User: "Test my changes"

Agent:

1. muggle_auth_status → Authenticated as user@example.com
2. Confirm: "Already logged in. Let's continue."
3. muggle_project_list → Found 1 local project
4. muggle_cloud_project_list → Found 3 cloud projects
5. Present combined list: "Which project to use?"
6. User: "1" (selects local project)
7. git status → Modified: LoginForm.tsx, AuthService.ts
8. git diff → Analyze changes (added error handling, updated validation)
9. muggle_use_case_list → Found 5 use cases
10. Present: "Your changes affect authentication. Found 2 related use cases:
    • User Authentication (3 test cases)
    • Password Reset (2 test cases) Which to test?"
11. User: "all"
12. muggle_test_case_list → 5 test cases total
13. muggle_test_script_list for each → 4 have scripts, 1 doesn't
14. Present execution plan, user confirms
15. Run 4 replays, 1 generation
16. Report summary: "4 passed, 1 new script generated"

Example 3: Create New Test

User: "Test the login flow on my app at localhost:3000"

Agent:

1. muggle_auth_status → Not authenticated
2. muggle_auth_login → User completes login
3. Confirm: "Logged in as user@example.com"
4. muggle_project_list → No local projects
5. muggle_cloud_project_list → Found 1 cloud project (different app)
6. Present list: "No matching projects found. Create new?"
7. User: "new"
8. muggle_project_create with name "Local App", url "http://localhost:3000"
9. muggle_use_case_save with goal "User can log in to the application"
10. muggle_test_case_save with login test details
11. muggle_test_script_list → Empty
12. muggle_execute_test_generation → Generates script
13. Report: "Test script generated with 5 steps. Ready to replay."

Quick Reference

Action	Tool/Command
Check auth status	muggle_auth_status
Login	muggle_auth_login
List local projects	muggle_project_list
List cloud projects	muggle_cloud_project_list
Analyze changes	git status, git diff
Pull project from cloud	muggle_cloud_pull_project
Pull use case from cloud	muggle_cloud_pull_use_case
Pull test case from cloud	muggle_cloud_pull_test_case
Create project	muggle_project_create
List use cases	muggle_use_case_list
Create use case	muggle_use_case_save
List test cases	muggle_test_case_list
Create test case	muggle_test_case_save
List test scripts	muggle_test_script_list
Generate script	muggle_execute_test_generation
Replay script	muggle_execute_replay
View results	muggle_run_result_get
List recent runs	muggle_run_result_list

Notes

• Login required: Always authenticate the user first before any testing operations.
• Project selection required: Always list both local and cloud projects, and wait for user to select one.
• Merge matching projects: Local and cloud projects with the same name should appear as ONE entry.
• Sync before testing: When a project has both local and cloud versions, always pull latest from cloud before testing.
• URL rewriting: When pulling from cloud, rewrite URLs to localhost and store original URL.
• Change-aware: When user says "test my changes", analyze git diff to identify impacted tests.
• Batch execution: Can run multiple tests in sequence, with summary report.
• No auto-publishing: This skill focuses on local testing only. Use publish-to-cloud skill separately.
• Reuse entities: Always check for existing projects/use cases/test cases before creating new ones.
• Confirm with user: When matches are ambiguous or multiple options exist, ask user to choose.
• No browser fallback: If Local MCP flow cannot proceed, fail fast with clear remediation steps.