--- name: muggle-test-import description: "Bring existing tests and test artifacts INTO Muggle Test — from Playwright, Cypress, PRDs, Gherkin feature files, test-plan docs, Notion exports, or any source. TRIGGER when the user wants to import, migrate, load, or convert existing test files or docs into Muggle Test — import my playwright tests, migrate from cypress to muggle, upload my PRD to muggle, turn this feature file into muggle test cases, or any .spec.ts/.cy.js/.feature/.md file plus muggle. DO NOT trigger for running or replaying scripts, scanning a site, generating new tests from scratch, or checking results." --- # Muggle Test Import > Telemetry first step: see [`_shared/telemetry-emit.md`](../_shared/telemetry-emit.md). Use `skillName: "muggle-test-import"`. This skill migrates existing test artifacts into Muggle Test. It reads your source files, structures them into use cases and test cases, gets your approval, then creates everything in a Muggle Test project via the API. ## Preferences Gates run per `preference-gates/README.md`. | Preference | Step | Decision it gates | |------------|------|-------------------| | `autoLogin` | 4 | Reuse saved credentials when auth is required | | `autoSelectProject` | 5 | Reuse last-used Muggle Test project for this repo | | `suggestRelatedUseCases` | 8a | Suggest related use cases after import | | `suggestRelatedTestCases` | 8b | Suggest related test cases after import | ## Concepts - **Use case**: A high-level feature or user workflow (e.g., "User Registration", "Checkout Flow") - **Test case**: A specific scenario within a use case (e.g., "Register with invalid email", "Complete checkout with Visa card") --- ## Step 1 — Identify source files Ask the user which files to analyse. Accept glob patterns, directory paths, or individual files. Common sources: | Source type | Typical patterns | |---|---| | Playwright | `**/*.spec.ts`, `**/*.test.ts`, `e2e/**` | | Cypress | `**/*.cy.js`, `**/*.cy.ts`, `cypress/integration/**` | | PRD / design doc | `*.md`, `*.txt`, `docs/**` | | Other | Any file the user points to | If the user is vague, scan the current directory for test file patterns and show what you found. Also ask for the **base URL of the app under test** if it is not embedded in the source files — you will need it for every test case. Confirm the final file list before reading. --- ## Step 2 — Analyse and extract structure The extraction strategy depends on the file type. Choose the right path before reading. ### Path A — PRD / design documents (preferred for document sources) Muggle Test has a native PRD processing workflow that extracts use cases more accurately than manual parsing. Use this path for `.md`, `.txt`, `.pdf`, or any prose document. After authentication and project selection (Steps 4–5), come back and: 1. Read the file and base64-encode its content 2. Call `muggle-remote-prd-file-upload` with the encoded content and filename 3. Call `muggle-remote-workflow-start-prd-file-process` using the fields returned by the upload (`prdFilePath`, `contentChecksum`, `fileSize`) plus the project URL 4. Poll `muggle-remote-wf-get-prd-process-latest-run` until the status is complete 5. After processing, call `muggle-remote-use-case-list` to retrieve the created use cases and their IDs — then skip Step 6 Pass 1 (use cases are already created) and go straight to creating any additional test cases if needed > Note: base64-encode in-memory using a Bash one-liner or Python — do not modify the file. If the native workflow fails or the document is in a format it cannot parse, fall back to Path B (manual extraction). ### Path B — Code-based test files (Playwright, Cypress, etc.) Read each file and extract a **use case → test case** hierarchy manually. - `describe()` / `test.describe()` block → use case name - `it()` / `test()` block → test case - Pull `page.goto('...')` calls for the URL - Derive `goal` and `expectedResult` from assertion text and comments ### Path B — General rules (applies to manual extraction) - Group thematically related tests under one use case when there is no explicit `describe()` grouping - Never leave `goal` or `expectedResult` blank — infer them from context - Assign priority: `HIGH` for critical paths and error handling, `MEDIUM` for secondary flows, `LOW` for edge cases Build an internal model before presenting anything to the user (Path B only): ``` Use Case: - TC1: | goal | expectedResult | precondition | priority | url - TC2: ... ``` --- ## Step 3 — Review with user Present the extracted structure clearly. Example format: ``` Found 3 use cases with 8 test cases: 1. User Authentication (3 test cases) ✦ [HIGH] Login with valid credentials ✦ [HIGH] Login with wrong password shows error ✦ [MEDIUM] Forgot password flow sends reset email 2. Shopping Cart (3 test cases) ✦ [HIGH] Add item to cart ✦ [MEDIUM] Remove item from cart ✦ [LOW] Cart persists after page reload 3. Checkout (2 test cases) ✦ [HIGH] Complete checkout with credit card ✦ [HIGH] Checkout fails with invalid payment info ``` Use `AskUserQuestion` to confirm: - "Looks good — proceed with import" - "I want to make changes first" If the user wants changes, incorporate feedback, then ask again. Only proceed after explicit approval. > For Path A (native PRD upload): present the use case/test case list that Muggle Test extracted > after the processing workflow completes, and ask the user to confirm before adding any > extra test cases manually. --- ## Step 4 — Authenticate (gated by `autoLogin`) Call `muggle-remote-auth-status` first. If **already authenticated** → gate `autoLogin` (per `preference-gates/README.md`): - `always` → skip to Step 5. - `never` → `muggle-remote-auth-login` with `forceNewSession: true`, then `muggle-remote-auth-poll`. - `ask` → run Picker 1 from `preference-gates/autoLogin.md` via `AskUserQuestion`; map the answer back to one of the actions above. If **not authenticated**: 1. Tell the user a browser window is about to open. 2. Call `muggle-remote-auth-login` (opens browser automatically). 3. Tell the user to complete login in the browser. 4. If the call returns before the user finishes, call `muggle-remote-auth-poll` to wait for completion. --- ## Step 5 — Pick or create a project (gated by `autoSelectProject`) A **project** is where all your imported use cases, test cases, and future test results are grouped on the Muggle AI dashboard. The per-repo project cache lives in `~/.muggle-ai/last-project.json`, in the entry keyed on `<cwd>` (via the `muggle-local-last-project-get` / `muggle-local-last-project-set` MCP tools). Look for `Muggle Test Last Project: id=… url=… name="…"` in session context. Gate `autoSelectProject` (per `preference-gates/README.md`). Cache: `Muggle Test Last Project` session line. - `always` + cache → use cached `projectId`, skip to Step 6. No cache → fall through to `ask`. - `never` → full project list; skip Picker 2. - `ask` → project list picker (see gate file for spec + Picker 2 override). Skip Picker 2 if "Create new project". ### Logic 1. Call `muggle-remote-project-list` (only when not satisfied by the `always` cache). 2. Use `AskUserQuestion` to present all projects as clickable options. Include the project URL in each label. Always include a "Create new project" option at the end. Prompt: `"Pick the project to import into:"` 3. **If creating a new project**, propose values based on what you learned from the source files: - **Name**: infer the app name from filenames, URLs, or document headings (e.g., "Acme App") - **Description**: "Imported from [filename(s)] — [date]" - **URL**: the base URL of the app under test Show the proposal and confirm before calling `muggle-remote-project-create`. --- ## Step 6 — Import Import in two passes using bulk-preview. Show progress to the user as you go. Both passes use Muggle Test's async bulk-preview MCP tools, which route prompts through OpenAI's Batch API for roughly ~50% of normal LLM cost. The flow is always: **submit → poll → persist**. ### Path A — Native PRD upload (for document files) If the source is a PRD or design document, use Muggle Test's built-in processing pipeline: 1. Read the file and base64-encode its content: ```bash base64 -i /path/to/doc.md ``` 2. Call `muggle-remote-prd-file-upload`: ``` projectId: <chosen project ID> fileName: "checkout-prd.md" contentBase64: "<base64 string>" contentType: "text/markdown" ``` 3. Call `muggle-remote-workflow-start-prd-file-process` using all fields returned by the upload: ``` projectId: <project ID> name: "Import from checkout-prd.md" description: "Auto-extract use cases from PRD" prdFilePath: <from upload response> originalFileName: "checkout-prd.md" url: <app base URL> contentChecksum: <from upload response> fileSize: <from upload response> ``` 4. Poll `muggle-remote-wf-get-prd-process-latest-run` every 5 seconds until status is complete. 5. Call `muggle-remote-use-case-list` to retrieve the created use cases and their IDs. 6. Present the extracted use cases to the user for review (Step 3), then skip Pass 1 below and go directly to Pass 2 if additional test cases are needed. If the upload or processing fails, fall back to Path B manual extraction. ### Path B — Manual import (for code-based test files) Run both passes below for Playwright, Cypress, or other test scripts. ### Shared limits (both passes) - Maximum 100 prompts per submit call. If you have more, split into batches of 100 and submit sequentially. - Maximum 4000 characters per `instruction`. - Maximum 3 in-flight bulk-preview jobs per project (the submit tool will error if exceeded). ### Shared error handling (both passes) The bulk-preview submit and get/cancel MCP tools surface structured error codes — look for these on any tool result and act accordingly: | Error code / symptom | What happened | What to do | |---|---|---| | `TOO_MANY_IN_FLIGHT_JOBS` (HTTP 429) | Already 3 in-flight jobs for this project | Tell the user: "There are already 3 bulk-preview jobs in progress for this project. Wait for them to finish, then retry." Stop. | | `QUOTA_EXCEEDED_PREFLIGHT` (HTTP 409) | Batch would blow past the account's quota for this resource | Show: "Your quota allows at most `<maxPromptsAllowed>` prompts in this batch (current headroom: `<headroom>`). Please reduce the batch and try again." Stop. | | `NOT_FOUND` on submit (HTTP 404) | Project or parent use case does not exist, or this server version doesn't expose bulk-preview yet | Tell the user which — double-check the IDs you passed. If you're confident the IDs are right, ask the user to make sure the prompt-service is up to date. Stop. | | `VALIDATION_ERROR` (HTTP 400) | A prompt exceeds limits (e.g. >4000 chars) or the prompt list is empty | Fix the offending prompts and retry. | | Payload > 1 MB (HTTP 413) | Body too large | Split into smaller batches. | ### Shared polling loop After a successful submit, poll with `muggle-remote-bulk-preview-job-get` (inputs: `projectId`, `jobId`) every 15 seconds. Show progress like: ``` Generating previews for "User Authentication"... (status: running, elapsed: 30s) ``` `status` values and what to do: | Status | Terminal? | Action | |---|---|---| | `queued` | No | Keep polling | | `submitted` | No | Keep polling | | `running` | No | Keep polling | | `succeeded` | Yes | All prompts processed — proceed to persist results | | `partial` | Yes | Some prompts succeeded — show summary, ask user whether to proceed | | `failed` | Yes | Job failed entirely — show `error.message` and stop | | `cancelled` | Yes | Job was cancelled — stop | | `expired` | Yes | Job expired before completing — tell user to retry | **If status is `partial`**, show: ``` Preview completed with partial results: <N> of <promptCount> generated successfully. Failed items: - [<clientRef>] "<source text>": <error message> Proceed with the <N> successful items, or cancel to review? ``` Use `AskUserQuestion` with options "Proceed with successful items" / "Cancel import". Only continue if the user chooses to proceed. If you need to abort an in-flight job, call `muggle-remote-bulk-preview-job-cancel` — the server picks up the request cooperatively within one harvester tick. ### Pass 1 — Create use cases (Path B only) 1. Call `muggle-remote-use-case-bulk-preview-submit` with one prompt per use case: ``` projectId: <chosen project ID> prompts: [ { clientRef: "uc-0", instruction: "<Use case name> — <one-sentence description>" }, ... ] ``` The call returns `{ jobId, status, kind, promptCount }`. 2. Run the **Shared polling loop** above until the job reaches a terminal status. 3. For each successful result (shape: `{ clientRef, index, status: "success", useCase: IUseCaseCreationRequest }`), call `muggle-remote-use-case-create` to persist it — no LLM is invoked, so this is fast and free: ``` projectId: <project ID> title: <from useCase.title> description: <from useCase.description> userStory: <from useCase.userStory> url: <from useCase.url> # optional useCaseBreakdown: <from useCase.useCaseBreakdown> status: <from useCase.status> # e.g. DRAFT priority: <from useCase.priority> # e.g. MEDIUM source: <from useCase.source> # e.g. PROMPT category: <from useCase.category> # optional ``` 4. Collect the returned `useCaseId` of each created use case — you'll need it for Pass 2. It is safe to persist use cases in parallel once the job is terminal. ### Pass 2 — Generate and create test cases For each use case, run a bulk-preview job to generate its test cases. 1. Call `muggle-remote-test-case-bulk-preview-submit`: ``` projectId: <project ID> useCaseId: <use case ID> prompts: [ { clientRef: "tc-0", instruction: "<title> | goal: <goal> | expectedResult: <expectedResult> | precondition: <precondition> | priority: <HIGH|MEDIUM|LOW> | url: <url>" }, ... ] ``` 2. Run the **Shared polling loop** above until the job reaches a terminal status. 3. Each successful result has this shape (note the fan-out): ```jsonc { "clientRef": "tc-0", "index": 0, "status": "success", "testCases": [ /* ITestCaseCreationRequest[] — fan-out 1–5 */ ] } ``` One input prompt may produce 1–5 test case items. For each item in `result.testCases`, call `muggle-remote-test-case-create`: ``` projectId: <project ID> useCaseId: <use case ID> title: <from testCase.title> description: <from testCase.description> goal: <from testCase.goal> expectedResult: <from testCase.expectedResult> precondition: <from testCase.precondition> priority: <from testCase.priority> url: <from testCase.url> ``` Print progress: `Creating test cases for "User Authentication"... (1/3)` It is safe to create test cases for different use cases in parallel once their bulk-preview jobs have reached a terminal status. However, **submit** bulk-preview jobs sequentially to avoid exceeding the 3 in-flight job cap per project. --- ## Step 7 — Summary When all imports are done, print a clean summary. Include: - The project name - Total use cases and test cases created - A line per use case with its test case count and a link to view it - A link to the project overview - If any items failed during preview (partial status), list them so the user can retry Construct view URLs using the Muggle Test dashboard URL pattern: - Project test cases: `https://www.muggle-ai.com/muggleTestV0/dashboard/projects/<projectId>/testcases` - Use case within project: `https://www.muggle-ai.com/muggleTestV0/dashboard/projects/<projectId>/testcases?useCaseId=<useCaseId>` Example: ``` ✅ Import complete! Project: Acme App → https://www.muggle-ai.com/muggleTestV0/dashboard/projects/proj_abc123/testcases Source: e2e/auth.spec.ts, e2e/cart.spec.ts Imported: 3 use cases · 8 test cases 1. User Authentication (3 test cases) → https://www.muggle-ai.com/muggleTestV0/dashboard/projects/proj_abc123/testcases?useCaseId=uc_111 2. Shopping Cart (3 test cases) → https://www.muggle-ai.com/muggleTestV0/dashboard/projects/proj_abc123/testcases?useCaseId=uc_222 3. Checkout (2 test cases) → https://www.muggle-ai.com/muggleTestV0/dashboard/projects/proj_abc123/testcases?useCaseId=uc_333 Next step: run /muggle:do to generate executable browser test scripts for these test cases. ``` ### Step 8 — Optional follow-up suggestions Two preferences gate optional follow-ups: `suggestRelatedUseCases` and `suggestRelatedTestCases`. Both are independent — handle each in turn. #### 8a — Related use cases (gated by `suggestRelatedUseCases`) The query is: "from the use cases already in this project, which ones are *not* in the import set but look related to it?" — surface them so the user can decide whether their import missed something the project already tracks. Gate `suggestRelatedUseCases` (per `preference-gates/README.md`): - `always` → run the query below. - `never` → skip. - `ask` → run Picker 1 from `preference-gates/suggestRelatedUseCases.md` via `AskUserQuestion`; map the answer back to one of the actions above. When running the query: 1. Call `muggle-remote-use-case-list` for the project. 2. Filter out any use case whose `useCaseId` is in the set you just imported in Step 6 (Pass 1). 3. Rank the remainder by semantic relevance to the imported titles/descriptions (substring overlap, shared keywords — best-effort, no LLM call needed). 4. Present the top 3-5 via `AskUserQuestion` with `allow_multiple: true`. Label each with `<title> — <one-line description>`. 5. For any the user selects, prompt to add follow-up test cases (treat each as a Pass 2 invocation: `muggle-remote-test-case-bulk-preview-submit` → poll → persist via `muggle-remote-test-case-create`). 6. If the filtered list is empty (the import covers everything in the project), say so and skip. #### 8b — Related test cases (gated by `suggestRelatedTestCases`) For each use case the user just created, surface other test cases already attached that the import didn't add — same idea, scoped to a single use case. Gate `suggestRelatedTestCases` (per `preference-gates/README.md`): - `always` → run the query below. - `never` → skip. - `ask` → run Picker 1 from `preference-gates/suggestRelatedTestCases.md` via `AskUserQuestion`; map the answer back to one of the actions above. When running the query, for each use case in the import: 1. Call `muggle-remote-test-case-list-by-use-case` with that `useCaseId`. 2. Filter out any test case you just created in Pass 2 of Step 6. 3. Present the remainder via `AskUserQuestion` with `allow_multiple: true`, labeled `[<priority>] <title> — <goal>`. 4. For any the user selects: nothing to create (they already exist) — just confirm to the user that those tests are now part of their Muggle Test project alongside the imported ones. 5. If a use case has no extra test cases, skip it silently.