MCP

Follow the instructions below to create a bunch of e2e tests in Lark:


------------------------- Instructions -------------------------

## Goal

Lark (getlark.ai) is an end-to-end testing platform. We will bulk-import workflows into getlark by collaborating with the user to understand their product area, generating comprehensive test cases, and importing them as a job through the configured lark MCP. This can be useful for onboarding (going from zero to full coverage) or expanding test coverage for a specific product surface.

getlark workflows can test any surface — web UIs, HTTP/GraphQL APIs, CLIs, shell scripts, data pipelines, or mixed flows. Do not assume the target is a browser URL unless the user says so.

## Prerequisites

1. Ensure that the lark MCP is configured so you can interact with the getlark API through it. If it isn't, ask the user to follow the instructions at https://docs.getlark.ai/mcp-quickstart to set it up. If the MCP is configured, list its available tools and perform a simple list-workflows action to verify it is working before proceeding. All getlark operations in this prompt MUST go through the configured lark MCP. Do not shell out to a CLI. Discover the appropriate tool names by inspecting the MCP.
2. Ask the user about what product area they want to generate tests for in Lark. This will typically be something like their API, dashboard, or something similar. They will give you relevant information and links for it (like API docs url, dashboard url, etc). 

## Procedure

### Step 1 — Understand the product area

Gather any additional information you need about the product area to build a good understanding about it. These could include things like:

- **What is the product/feature?** (e.g., "our checkout flow", "the user management API", "the CLI tool for data imports")
- **What is the target?** (URL, API base, CLI binary, script path, etc.)
- **Are there specific user journeys or critical paths to cover?**
- **Are there credentials or secret contexts needed?** If yes, confirm they exist by listing secret contexts through the lark MCP.

If the user invoked the skill with a description already, use that as the starting point and ask only clarifying questions for gaps. 

Once you have a good understanding of the product to test, move on to next step.

### Step 2 — Assess existing coverage

Before generating new test cases, list all existing workflows through the lark MCP to understand what coverage already exists. Use a page size of 100 and paginate until all workflows have been retrieved.

Summarize the existing coverage for the user:

- Group workflows by feature area or theme (infer from names/descriptions)
- Highlight which areas of the product already have tests
- Identify gaps — areas the user mentioned in Step 1 that have no existing workflows

This prevents duplicate coverage and helps focus the new test cases on genuine gaps. If the user's target product area is already well-covered, let them know and ask whether they want to supplement with edge cases or shift focus to a different area.

### Step 3 — Research and generate test cases

**Aim for solid coverage.** The goal of bulk import is to seed broad, useful coverage — distinct user flows, important edge cases, and likely failure modes. Between AI driven and deterministic test, prefer the latter when possible since they are cheap and faster. 

Based on the product area and the coverage gaps identified in Step 2, develop a well-rounded set of test cases. Think about:

- **Happy paths** — core user journeys that must always work (login, checkout, CRUD operations, etc.)
- **Alternate user flows** — different roles, plan tiers, entry points, devices, or paths to the same outcome
- **Edge cases** — boundary conditions, empty states, max-length inputs, concurrent actions, special characters
- **Error handling** — invalid inputs, unauthorized access, network failures, graceful degradation
- **Cross-feature interactions** — flows that span multiple features or services
- **Regression-prone areas** — features that break often or have complex dependencies

For each test case, write a clear, actionable description about what to test. The description is what the AI agent reads at runtime to perform the test. You don't need to be too explicit with instructions (like specifying exact API request to make, etc). You can describe the user flow you want to test and Lark systems will implement the test appropriately.

**Choosing mode**: Prefer `deterministic` when possible — deterministic tests are cheaper and faster to run. Use `ai_driven` only when the test requires adaptive behavior (e.g., dynamic content, unpredictable UI states, flows that change frequently). A good default split is mostly deterministic with a handful of ai_driven tests for flows where flexibility is genuinely needed.

**Organizing with groups**: Use workflow groups to keep the new tests organized by product area or feature. List existing groups through the lark MCP. If a relevant group already exists, assign the new workflows to it using `group_id`. If none fits, ask the user about creating new group(s) (e.g., "Checkout Flow", "User Management API") through the lark MCP and use its ID in the import file. Well-organized groups make it easy to invoke all related tests together and keep the dashboard navigable as coverage grows. Grouping tests together by a logical domain is usually a nice approach (as opposed to putting all in a single broad group like API or dashboard).

### Step 4 — Write the import JSON file

Create a JSON file (default: `workflows-import.json` in the current working directory) that follows the `workflow_import` schema:

```json
{
  "workflows": [
    {
      "name": "Descriptive Test Name",
      "description": "Go to <target>, perform <action 1>, then <action 2>, assert <expected outcome>.",
      "mode": "ai_driven",
      "secret_contexts": ["context-name"],
      "group_id": "wgrp_..."
    }
  ]
}
```

Schema rules:
- `name` (string, required) — concise, Title-Case name (3–8 words) capturing the test intent.
- `description` (string, required) — full natural-language test steps. Include the target, actions, and assertions. This is what the AI agent uses to execute the test.
- `mode` (required) — `"deterministic"` (locked to generated script, cheaper and faster) or `"ai_driven"` (tolerates minor UI changes, more flexible). Prefer `deterministic` where possible; use `ai_driven` only for flows that genuinely need adaptive behavior.
- `secret_contexts` (array of strings or null, optional) — names of secret contexts the workflow needs for auth/tokens.
- `group_id` (string or null, optional) — workflow group ID to assign the workflow to.

No additional properties are accepted.

### Step 5 — Review and iterate with the user

Present the generated test cases to the user in a readable format (table or numbered list showing name + summary of what each test covers). Ask them to review and suggest changes:

- Are there missing test cases?
- Should any be removed or merged?
- Are descriptions accurate and detailed enough?
- Are the right secret contexts and groups assigned?

Iterate on the JSON file based on feedback. Continue until the user confirms the test cases are ready for import. Do not create the import job without explicit user approval.

### Step 6 — Create the import job

Once the user approves, create the import job through the lark MCP, passing:
- a descriptive `name` for the job (e.g., "Import Checkout Flow Tests" or "Onboarding - User Management API Coverage")
- the `workflows` array from `./workflows-import.json` inline as the job input

The create-job tool validates the payload server-side and will NOT create a job if it is invalid — it returns the validation errors instead. If it returns errors, read them, fix the JSON file accordingly, and call it again (no job is created on a failed attempt, so retrying after a fix is safe). Common issues:
- Missing required fields (`name`, `description`, `mode`)
- Invalid `mode` value (must be exactly `"ai_driven"` or `"deterministic"`)
- Empty `workflows` array
- Extra properties not in the schema
- Non-unique or empty strings

Once it succeeds it returns the created job resource (with a job `id`) — do not call it again for the same payload.

### Step 7 — Report result

The create-job tool returns the job resource as JSON. Extract and report:

- Job `id`
- Job `status` (typically `pending` or `running` initially)
- **Dashboard URL**: `https://dashboard.getlark.ai/jobs/<id>`

Tell the user the workflow import job was created successfully and share the dashboard URL. Let them know they can:
- Track progress on the dashboard
- Check job status through the lark MCP with the job ID
- Cancel if needed through the lark MCP with the job ID

## Guidelines for writing good test descriptions

- Start with the target (URL, API endpoint, CLI command, etc.)
- Use imperative verbs: "Go to", "Click", "Submit", "Assert", "Verify", "Enter", "Wait for"
- End with a clear assertion of expected outcome
- Reference credentials by secret context name, never hardcode secrets in descriptions
- Keep each workflow focused on one logical user journey — don't cram multiple unrelated flows into a single workflow
- Be specific enough that someone unfamiliar with the product can follow the steps

## Example

User says: "I want to add test coverage for our e-commerce checkout flow at https://shop.example.com"

After research and iteration, produce:

```json
{
  "workflows": [
    {
      "name": "Guest Checkout Happy Path",
      "description": "Go to https://shop.example.com/products, add the first available product to cart, proceed to checkout as a guest, fill shipping with valid US address, select standard shipping, enter test card 4242424242424242, submit order, assert order confirmation page shows order number.",
      "mode": "ai_driven",
      "secret_contexts": ["staging"]
    },
    {
      "name": "Empty Cart Checkout Guard",
      "description": "Go to https://shop.example.com/cart with an empty cart, attempt to click Proceed to Checkout, assert the checkout button is disabled or a message says 'Your cart is empty'.",
      "mode": "ai_driven"
    },
    {
      "name": "Apply Discount Code",
      "description": "Go to https://shop.example.com/products, add any product to cart, go to cart, enter discount code SAVE10 in the promo field, click Apply, assert the total decreases and a 'Discount applied' message is shown.",
      "mode": "ai_driven",
      "secret_contexts": ["staging"]
    },
    {
      "name": "Invalid Payment Card Rejected",
      "description": "Go to https://shop.example.com/products, add a product to cart, proceed to checkout as guest, fill valid shipping, enter invalid card number 1234567890123456, submit payment, assert an error message about invalid card is displayed and order is not placed.",
      "mode": "ai_driven",
      "secret_contexts": ["staging"]
    }
  ]
}
```

Then create the import job through the lark MCP with the name "Import Checkout Flow Tests", passing the `workflows` array inline.

Report the dashboard URL to the user.

## Failure modes

- **Validation errors**: The create-job tool returns the errors without creating a job. Fix the JSON and call it again.
- **Auth errors**: The lark MCP is likely not authenticated or not configured correctly. Ask the user to revisit https://docs.getlark.ai/mcp-quickstart to confirm the MCP setup.
- **Unknown secret context**: Verify by listing secret contexts through the lark MCP before including in the file.
- **Unknown group ID**: Verify by listing workflow groups through the lark MCP before including in the file.

## Do NOT

- Do not shell out to a `getlark` CLI. All getlark operations must go through the configured lark MCP.
- Do not create the import job through the lark MCP more than once for the same payload. Each call creates a separate job — calling it twice will import the workflows twice, resulting in duplicates. If the job was created successfully (returned a job ID and dashboard URL), do not retry it.
- Do not create the import job without user approval of the test cases.
- Do not hardcode secrets or API keys in workflow descriptions. Use secret contexts.
- Do not create excessively vague descriptions. Each must be actionable by an AI agent at runtime.
- Do not invent secret context names or group IDs — verify they exist first via the lark MCP.