wopee-mcp 1.30.2 → 1.32.0

package/README.md

@@ -237,6 +237,11 @@ Generates a specific file(artifact) for the selected suite.
 - **Parameters:**
   - `suiteUuid` - The UUID of the suite
   - `type` - `"APP_CONTEXT" | "GENERAL_USER_STORIES" | "USER_STORIES_WITH_TEST_CASES" | "TEST_CASES" | "TEST_CASE_STEPS" | "REUSABLE_TEST_CASES" | "REUSABLE_TEST_CASE_STEPS"`
+  - `mode` _(optional, `TEST_CASES` only)_ - `"UPDATE"` (default) keeps existing test cases with their steps and run history; `"CREATE"` replaces the test cases in scope and deletes their steps, runs and code
+  - `selectedUserStories` _(optional)_ - user story ids to limit `TEST_CASES` / `TEST_CASE_STEPS` to, e.g. `["US001"]`; empty means every story
+  - `selectedTestCases` _(optional)_ - test case identifiers to limit `TEST_CASE_STEPS` to, e.g. `["US001:TC002"]`
+  - `instructions` _(optional)_ - the change request passed to the AI engine
+  - `async` _(optional, `TEST_CASES` / `USER_STORIES_WITH_TEST_CASES`)_ - return as soon as the run is queued instead of waiting for the artifact
 - **Returns:** Generated output in case of successful generation.
 
 **Example Usage:**
@@ -344,6 +349,26 @@ Fetch test results for suite <suiteUuid>
 Show me the executed test cases for my latest analysis suite
 ```
 
+### Reporting
+
+#### `wopee_create_github_issue`
+
+Files a GitHub issue into the repository linked to the current project. Given a failed run's `executedTestCaseUuid`, Wopee.io adds what it knows about that run below your text: the failing step, expected vs actual, the failing step's screenshot and a link to the run in Commander.
+
+- **Parameters:**
+  - `title` - The issue title
+  - `body` _(optional)_ - Markdown, kept verbatim above the run evidence
+  - `labels` _(optional)_ - Labels to apply, e.g. `["bug"]`. GitHub may skip labels the repository doesn't have; the result says which were applied
+  - `executedTestCaseUuid` _(optional)_ - The run to attach evidence from, as shown by `wopee_fetch_recent_executions` or `wopee_dispatch_agent`
+- **Returns:** The issue number and URL, plus notes on anything left out (e.g. a screenshot that could not be uploaded)
+- **Requirements:** The issue is created by the Wopee.io GitHub App and names you in its body. The App's installation needs the **Issues: Read & write** repository permission, and **Contents: Read & write** for the screenshot, which is committed to a separate `wopee-issue-assets` branch. That branch has no shared history with your code and is safe to delete; deleting it only breaks the images in existing issues.
+
+**Example Usage:**
+
+```
+File the failed checkout test as a GitHub issue
+```
+
 ## Typical Workflow
 
 1. **Start with a suite:**
@@ -369,6 +394,9 @@ Show me the executed test cases for my latest analysis suite
    - Use `wopee_fetch_executed_test_cases` to check detailed status and reports for a specific suite
    - Or use the `fetch-test-results` prompt for a formatted summary of all test results
 
+6. **Report failures:**
+   - Use `wopee_create_github_issue` with the failed run's `executedTestCaseUuid` to file it into your repository
+
 ## Available Prompts
 
 ### `fetch-project-summary`

package/build/tools/shared/factories.js

@@ -1,4 +1,5 @@
 import { getConfig } from "../../utils/getConfig.js";
+import { generationOptions } from "../wopee_generate_artifact/request.js";
 export const createFetchArtifactInput = (input) => {
     const { WOPEE_PROJECT_UUID } = getConfig();
     if (!WOPEE_PROJECT_UUID)
@@ -27,10 +28,8 @@ export const createGenerateAIDataInput = (input) => {
             additionalVariables: null,
         },
         continueGeneration: false,
-        extraPrompt: null,
-        selectedUserStories: null,
-        selectedTestCases: null,
         sourceSuiteUuid: null,
+        ...generationOptions(input),
     };
 };
 export const createUpdateArtifactInput = (input) => {

package/build/tools/shared/gql-queries.js

@@ -295,11 +295,26 @@ export const FetchRecentExecutedTestCases = `
   }
 `;
 export const CreateGitHubIssue = `
-  mutation CreateGitHubIssue($projectUuid: ID!, $title: String!, $body: String!, $labels: [String!]) {
-    createGitHubIssue(projectUuid: $projectUuid, title: $title, body: $body, labels: $labels) {
+  mutation CreateGitHubIssue(
+    $projectUuid: ID!
+    $title: String!
+    $body: String!
+    $labels: [String!]
+    $executedTestCaseUuid: ID
+  ) {
+    createGitHubIssue(
+      projectUuid: $projectUuid
+      title: $title
+      body: $body
+      labels: $labels
+      executedTestCaseUuid: $executedTestCaseUuid
+    ) {
       url
       number
       title
+      screenshotAttached
+      labelsApplied
+      warnings
     }
   }
 `;

package/build/tools/shared/handlers.js

@@ -1,6 +1,7 @@
 import { FetchArtifactInputSchema, UpdateArtifactInputSchema, GenerateAIDataInputSchema, } from "./schemas.js";
 import { FetchArtifact, UpdateArtifact } from "./gql-queries.js";
 import { createFetchArtifactInput, createUpdateArtifactInput, createGenerateAIDataInput, } from "./factories.js";
+import { isQueuedGeneration } from "../wopee_generate_artifact/request.js";
 import { requestClient } from "../../utils/requestClient.js";
 import { _compactArtifactContentForModel, _convertToArtifactType, _parseError, _parseGenerateArtifactType, } from "./helpers.js";
 export async function fetchArtifact(input) {
@@ -63,6 +64,15 @@ export async function generateAIDataFile(input) {
                     },
                 ],
             };
+        if (isQueuedGeneration(input))
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Queued: ${description}. It runs in the background and can take several minutes; read the result with wopee_fetch_artifact once it has finished.`,
+                    },
+                ],
+            };
         const convertedType = _convertToArtifactType(input.type);
         return await fetchArtifact({
             suiteUuid: parsedInput.suiteUuid,

package/build/tools/shared/schemas.js

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { ArtifactType, GenerateArtifactType } from "./types.js";
+import { ArtifactType, GenerateArtifactType, TestCaseGenerationMode, } from "./types.js";
 var CookiesPreference;
 (function (CookiesPreference) {
     CookiesPreference["ACCEPT_ALL"] = "ACCEPT_ALL";
@@ -35,6 +35,31 @@ export const GenerateAIDataHandlerInputSchema = z.object({
         description: "UUID of the analysis suite to generate artifacts for. Get this from wopee_create_blank_suite or wopee_fetch_analysis_suites.",
     })
         .min(1, "Suite UUID is required"),
+    mode: z
+        .nativeEnum(TestCaseGenerationMode, {
+        description: "TEST_CASES only. UPDATE (default) keeps every existing test case with its steps and run history, and adds or changes test cases around them. CREATE replaces the test cases of the stories in scope — of the whole suite when selectedUserStories is empty — and deletes their steps, run history and Playwright code. Use CREATE only when the user explicitly asks to start over.",
+    })
+        .default(TestCaseGenerationMode.UPDATE),
+    selectedUserStories: z
+        .array(z.string(), {
+        description: "User story ids to limit the generation to, e.g. ['US001', 'US003']. Leave empty for every story in the suite. Used by TEST_CASES and TEST_CASE_STEPS.",
+    })
+        .optional(),
+    selectedTestCases: z
+        .array(z.string(), {
+        description: "Test case identifiers to limit TEST_CASE_STEPS to, e.g. ['US001:TC002']. Leave empty for every test case in scope. Regenerating steps replaces the steps those test cases have.",
+    })
+        .optional(),
+    instructions: z
+        .string({
+        description: "What the user asked for, in their words, e.g. 'add a negative test for an expired card'. Passed to the AI engine as the change request; without it, UPDATE removes no test case.",
+    })
+        .optional(),
+    async: z
+        .boolean({
+        description: "TEST_CASES and USER_STORIES_WITH_TEST_CASES only. true returns as soon as the generation is queued instead of waiting for it (a large suite can take several minutes); the content is then read later with wopee_fetch_artifact. Default false: wait and return the generated artifact.",
+    })
+        .optional(),
 });
 export const GenerateAIDataInputSchema = z.object({
     projectUuid: z.string().min(1, "Project UUID is required"),
@@ -45,6 +70,8 @@ export const GenerateAIDataInputSchema = z.object({
     selectedTestCases: z.array(z.string()).nullish(), // ["US001:TC001", "US003:TC002", "US015:TC033"]
     suiteAnalysisConfig: SuiteAnalysisConfigSchema,
     continueGeneration: z.boolean().nullish().default(false),
+    mode: z.nativeEnum(TestCaseGenerationMode).nullish(),
+    async: z.boolean().nullish(),
 });
 export const FetchArtifactHandlerInputSchema = z.object({
     type: z.nativeEnum(ArtifactType, {

package/build/tools/shared/types.js

@@ -31,6 +31,11 @@ export var GenerateArtifactType;
     GenerateArtifactType["REUSABLE_TEST_CASES"] = "REUSABLE_TEST_CASES";
     GenerateArtifactType["REUSABLE_TEST_CASE_STEPS"] = "REUSABLE_TEST_CASE_STEPS";
 })(GenerateArtifactType || (GenerateArtifactType = {}));
+export var TestCaseGenerationMode;
+(function (TestCaseGenerationMode) {
+    TestCaseGenerationMode["UPDATE"] = "UPDATE";
+    TestCaseGenerationMode["CREATE"] = "CREATE";
+})(TestCaseGenerationMode || (TestCaseGenerationMode = {}));
 export var ArtifactType;
 (function (ArtifactType) {
     ArtifactType["APP_CONTEXT"] = "APP_CONTEXT";

package/build/tools/wopee_create_github_issue/format.js

@@ -0,0 +1,21 @@
+// The text an MCP caller reads back after filing an issue.
+//
+// No runtime imports, which keeps it unit-testable under `node --test`.
+export function formatIssueCreated(issue, { withRunEvidence }) {
+    const lines = [
+        "GitHub issue created successfully:",
+        `- Title: ${issue.title}`,
+        `- Number: #${issue.number}`,
+        `- URL: ${issue.url}`,
+    ];
+    if (issue.labelsApplied?.length) {
+        lines.push(`- Labels: ${issue.labelsApplied.join(", ")}`);
+    }
+    if (withRunEvidence) {
+        lines.push(`- Run evidence: failing step, expected vs actual and the Commander report link added; screenshot ${issue.screenshotAttached ? "attached" : "not attached"}`);
+    }
+    for (const warning of issue.warnings ?? []) {
+        lines.push(`- Note: ${warning}`);
+    }
+    return lines.join("\n");
+}

package/build/tools/wopee_create_github_issue/index.js

@@ -4,21 +4,27 @@ import { requestClient } from "../../utils/requestClient.js";
 import { _parseError } from "../shared/helpers.js";
 import { ToolName } from "../shared/types.js";
 import { CreateGitHubIssue } from "../shared/gql-queries.js";
+import { formatIssueCreated } from "./format.js";
 const InputSchema = z.object({
     title: z.string().describe("The title of the GitHub issue"),
     body: z
         .string()
-        .describe("The body/description of the GitHub issue (supports Markdown)"),
+        .optional()
+        .describe("The body/description of the GitHub issue (supports Markdown). Kept verbatim, above anything Wopee.io adds from the test run."),
     labels: z
         .array(z.string())
         .optional()
         .describe("Optional labels to apply to the issue (e.g., ['bug', 'testing'])"),
+    executedTestCaseUuid: z
+        .string()
+        .optional()
+        .describe("UUID of the executed test case the issue is about (the executedTestCaseUuid shown by wopee_fetch_recent_executions and wopee_dispatch_agent, or uuid in wopee_fetch_executed_test_cases). When set, Wopee.io adds the failing step, expected vs actual, the failing step's screenshot and a link to the run in Commander, so the body only needs your own analysis."),
 });
 export const wopeeCreateGithubIssue = {
     name: ToolName.WOPEE_CREATE_GITHUB_ISSUE,
     config: {
         title: "Create GitHub issue",
-        description: "Create a new GitHub issue in the project's connected repository. Use this to report bugs found during testing, track test failures, or create action items from chat discussions. The issue will be created in the GitHub repository linked to the current project. Requires the project to have GitHub integration configured and WOPEE_PROJECT_UUID to be set.",
+        description: "Create a new GitHub issue in the project's connected repository. Use this to report bugs found during testing, track test failures, or create action items from chat discussions. For a failed test, pass its executedTestCaseUuid so the issue carries the run's evidence (failing step, expected vs actual, screenshot, report link). The issue is created by the Wopee.io GitHub App and names the requester in its body. Requires a GitHub repository linked to the project and WOPEE_PROJECT_UUID to be set.",
         inputSchema: InputSchema.shape,
     },
     handler: async (input) => {
@@ -33,15 +39,18 @@ export const wopeeCreateGithubIssue = {
             const result = await requestClient(CreateGitHubIssue, {
                 projectUuid: WOPEE_PROJECT_UUID,
                 title: input.title,
-                body: input.body,
+                body: input.body ?? "",
                 labels: input.labels || [],
+                ...(input.executedTestCaseUuid && {
+                    executedTestCaseUuid: input.executedTestCaseUuid,
+                }),
             });
             if (!result?.createGitHubIssue)
                 return {
                     content: [
                         {
                             type: "text",
-                            text: "Failed to create GitHub issue. Make sure the project has GitHub integration configured.",
+                            text: "Failed to create GitHub issue. Make sure the project has a GitHub repository linked.",
                         },
                     ],
                 };
@@ -49,7 +58,9 @@ export const wopeeCreateGithubIssue = {
                 content: [
                     {
                         type: "text",
-                        text: `GitHub issue created successfully:\n- Title: ${result.createGitHubIssue.title}\n- Number: #${result.createGitHubIssue.number}\n- URL: ${result.createGitHubIssue.url}`,
+                        text: formatIssueCreated(result.createGitHubIssue, {
+                            withRunEvidence: !!input.executedTestCaseUuid,
+                        }),
                     },
                 ],
             };

package/build/tools/wopee_fetch_recent_executions/index.js

@@ -52,6 +52,8 @@ export const wopeeFetchRecentExecutions = {
                 // INCOMPLETE on top, and reporting it as FAILED tells the user their app is broken.
                 const status = tc.agentReportStatus ?? tc.executionStatus;
                 lines.push(`- ${tc.userStoryId}:${tc.testCaseId} [${tc.analysisIdentifier}] → ${status} (${tc.updatedAt})`);
+                // The handle wopee_create_github_issue takes to attach this run's evidence.
+                lines.push(`  executedTestCaseUuid: ${tc.uuid}`);
                 // Any report, not only a FINISHED run's: an incomplete run's report is what names the
                 // infrastructure error behind it.
                 if (tc.agentReport) {

package/build/tools/wopee_generate_artifact/index.js

@@ -5,7 +5,7 @@ export const wopeeGenerateArtifact = {
     name: ToolName.WOPEE_GENERATE_ARTIFACT,
     config: {
         title: "Generate test artifacts",
-        description: "Generate AI-powered test artifacts for a suite using the Wopee.io AI engine. Each call creates one artifact type — call multiple times for different types. Generation order matters: APP_CONTEXT must be generated before user stories, and user stories before test cases. If called out of order, the AI may produce lower quality results. On success, returns confirmation that generation started. Use wopee_fetch_artifact to retrieve the generated content once ready. Do NOT use this to update existing artifacts — use wopee_update_artifact instead. Generating the same type again overwrites the previous version.",
+        description: "Generate AI-powered test artifacts for a suite using the Wopee.io AI engine. Each call creates one artifact type — call multiple times for different types. Generation order matters: APP_CONTEXT must be generated before user stories, and user stories before test cases. If called out of order, the AI may produce lower quality results. On success, returns confirmation that generation started. Use wopee_fetch_artifact to retrieve the generated content once ready. Do NOT use this to hand-edit existing artifacts — use wopee_update_artifact instead. TEST_CASES runs in UPDATE mode by default: existing test cases keep their steps and run history, and `instructions` says what to add or change. Destructive generations are mode CREATE (replaces the test cases in scope and deletes their steps, runs and code), USER_STORIES_WITH_TEST_CASES (rebuilds every story and test case) and TEST_CASE_STEPS (replaces the steps of the test cases in scope): use them only when the user explicitly asks for that, and scope them with selectedUserStories / selectedTestCases when the user named stories or test cases.",
         inputSchema: GenerateAIDataHandlerInputSchema.shape,
     },
     handler: async (input) => await generateAIDataFile(input),

package/build/tools/wopee_generate_artifact/request.js

@@ -0,0 +1,19 @@
+const TEST_CASES = "TEST_CASES";
+/** The generations the api can queue and answer at once; every other one always waits. */
+const QUEUEABLE_TYPES = [
+    TEST_CASES,
+    "USER_STORIES_WITH_TEST_CASES",
+];
+/** Whether this request is answered as soon as the api has queued it. */
+export const isQueuedGeneration = (input) => input.async === true && QUEUEABLE_TYPES.includes(input.type);
+/** An empty scope means every story or test case, which the api reads as null. */
+const scope = (ids) => ids && ids.length > 0 ? ids : null;
+export const generationOptions = (input) => ({
+    extraPrompt: input.instructions?.trim() || null,
+    selectedUserStories: scope(input.selectedUserStories),
+    selectedTestCases: scope(input.selectedTestCases),
+    // Sent on every test case generation, never left to the api's default: CREATE is the one mode
+    // that deletes work, and an older api treats a missing mode as CREATE.
+    ...(input.type === TEST_CASES ? { mode: input.mode } : {}),
+    ...(isQueuedGeneration(input) ? { async: true } : {}),
+});

package/package.json

@@ -4,7 +4,7 @@
   "bin": {
     "wopee-mcp": "./build/index.js"
   },
-  "version": "1.30.2",
+  "version": "1.32.0",
   "mcpName": "io.github.Wopee-io/wopee-mcp",
   "description": "Wopee.io MCP server for autonomous testing platform",
   "main": "./build/index.js",