Workflow Examples

View as Markdown

These examples show how Shiplight MCP integrates into AI-driven development — verifying UI changes as you code, and automatically creating test cases from your work.

Verify UI Changes During Development

After implementing or modifying a frontend feature, the AI coding agent verifies the changes by launching a browser and interacting with the UI — no manual checking needed.

Example prompt:

I just added a "Forgot Password?" link below the login form.
Use Shiplight to verify it works.

What the agent does:

1. new_session — launch a browser with a saved storage state to skip login
2. get_dom — get the DOM with element indices (+ take_screenshot if visual confirmation needed)
3. act — interact with the new link, fill in the form, check the result
4. get_dom / take_screenshot — visually confirm the expected behavior
5. close_session — clean up

If login is needed and no storage state exists, the agent logs in and calls save_storage_state to cache the session for future use.

After verification, the agent can save the action entities from the session as a YAML test flow — ready to upload to Shiplight cloud for continuous regression testing.

Full workflow:

1. new_session(starting_url, storage_state_path)
2. get_dom → get DOM with element indices (+ take_screenshot for visual info)
3. act → exercise the UI changes
4. get_dom / take_screenshot → confirm the result
5. Save a YAML test flow with collected action entities
6. close_session

Automated Test Creation with Claude Code

Claude Code supports custom agents that automate multi-step workflows. The shiplight-test-creator agent handles the full test creation lifecycle — from writing the YAML draft, to exploring the UI for locators, to uploading to Shiplight cloud.

Example prompt:

Create a test case for the checkout flow on our staging environment.

What the agent does (7 phases):

Phase 1: Design

Writes a YAML test flow draft in natural language:

goal: Verify user can complete checkout
url: https://staging.example.com/cart
statements:
  - Click the "Proceed to Checkout" button
  - Enter shipping address details
  - Select "Standard Shipping"
  - Click "Place Order"
  - "VERIFY: Order confirmation page shows order number"
teardown:
  - Cancel the created order

Phase 2: Explore UI

Opens a browser session and walks through every step, collecting locators and action entities using get_dom, act, and get_locator.

Phase 3: Enrich

Replaces natural language DRAFTs with deterministic ACTION statements using the collected locators:

- description: Click the Proceed to Checkout button
  action_entity:
    action_data:
      action_name: click
    locator: "getByRole('button', { name: 'Proceed to Checkout' })"

Each DRAFT that describes multiple interactions is decomposed into one ACTION per atomic interaction.

Phase 4: Local execution

Exports the enriched YAML as a standalone Playwright test via export_yaml_to_test and runs it locally. This provides fast feedback without cloud infrastructure. See Local Testing.

Phase 5: Feedback & refinement

If the local test fails, the agent adjusts the YAML — fixing selectors, reordering steps, adding missing assertions — and re-runs locally until it passes.

Phase 6: Upload

Saves the test case to Shiplight cloud via save_test_case. On first save, a new test case is created and the returned YAML includes an embedded test_case_id linking the local file to the remote test case. Returns flow stats showing how many statements are enriched vs. remaining DRAFTs.

Phase 7: Cloud execution & updates

Triggers a cloud execution, polls for results, and analyzes any failures:

• Test flow issue (wrong locator, missing wait) → fixes the YAML and calls save_test_case again (the embedded test_case_id ensures the existing test case is updated, not duplicated)
• Product bug → reports to you with evidence
• Infrastructure issue → reports to you

The agent limits itself to 3 fix iterations before asking for help.

Setting Up the Agent

Add the agent configuration to .claude/agents/shiplight-test-creator.md in your project. See Claude Code custom agents documentation for setup details.

Once configured, Claude Code automatically delegates test creation tasks to the agent:

You: Create a test case for the login flow
Claude: I'll use the shiplight-test-creator agent to create a
        comprehensive test case for the login functionality.
        [agent runs through all 7 phases autonomously]