# STLC Agents — End-to-End Walkthrough: Azure DevOps

> ADO pipeline: PBI / Bug / Feature → test cases → Gherkin → Playwright TypeScript → Helix-QA.
> For the Jira Cloud pipeline see [WALKTHROUGH-JIRA.md](WALKTHROUGH-JIRA.md).

---

## Overview

This walkthrough traces the full pipeline using a concrete example: **User Profile Photo Management** — a feature allowing users to upload, crop, and update their profile photo.

The ADO pipeline uses four MCP servers, invoked in sequence by a single AI coding assistant session. Setup takes under five minutes; the full pipeline for one PBI runs in approximately 15–20 minutes of AI-assisted work.

---

## Setup

```bash
npm install -g @qa-gentic/stlc-agents
qa-stlc init --vscode --integration ado
npx @playwright/mcp@latest --port 8931
```

Copy `.env.example` to `.env`:

```env
ADO_ORGANIZATION_URL=https://dev.azure.com/your-org
ADO_PROJECT_NAME=YourProject
ADO_PAT=your-personal-access-token
APP_BASE_URL=https://your-app.example.com
APP_EMAIL=your-test-email@example.com
APP_PASSWORD=your-test-password
```

---

## Phase 1 — Manual Test Case Generation (`qa-test-case-manager`)

### What you say

> "Generate test cases for work item #12345 in MyProject at https://dev.azure.com/myorg"

### Step 1.1 — Fetch the work item

`fetch_work_item(work_item_id=12345)` calls the ADO REST API, strips HTML from rich-text fields, and runs `_extract_coverage_hints()`. For this example, the response flags:

```
file_size_boundary  image_manipulation  toast_notifications
cancel_flows        post_action_state   file_formats
```

### Step 1.2 — Deduplication gate

`get_linked_test_cases()` fetches existing TCs. The agent diffs by title and only creates net-new cases. Re-running the pipeline on the same work item is always safe.

### Step 1.3 — Create and link

`story_points = 5` → Medium complexity → 6–12 test cases planned.

`create_and_link_test_cases()` generates `Microsoft.VSTS.TCM.Steps` XML for each case, then adds a `TestedBy-Forward` link from each TC back to PBI #12345.

### What appears in ADO

- 8 test cases created under the Tests tab of PBI #12345
- Area path and iteration path automatically inherited from the parent work item
- Each test case titled with a `TC_{id}_{seq}` prefix for traceability

---

## Phase 2 — Gherkin BDD Generation (`qa-gherkin-generator`)

### What you say

> "Generate a Gherkin regression suite for Feature #11000 in MyProject"

### Step 2.1 — Fetch the feature hierarchy

`fetch_feature_hierarchy(feature_id=11000)` walks Feature → PBIs → Bugs and for each child fetches linked test cases with their full XML steps. A best-practice Gherkin example is embedded in the API response as a style reference.

### Step 2.2 — Generate the feature file

The coding agent reads all test cases, identifies feature-level journeys, and writes scenarios following the skill rules:

- 5–10 scenarios per feature file
- `@smoke` on the primary happy path
- `@regression` on all others
- `Scenario Outline` for boundary/data-driven tests
- `Background` only when 2+ scenarios share identical preconditions
- Explicit navigation steps in every scenario

Example generated output:

```gherkin
@user_profile @regression
Feature: User Profile Photo Management
  As an authenticated user
  I want to manage my profile photo

  Background:
    Given user logs in with Microsoft SSO as "standard_user"

  @smoke
  Scenario: User uploads a valid photo and sees confirmation
    Given the user navigates to the Profile Photo section
    When the user selects a valid JPG file under 5 MB
    And the user adjusts the crop and clicks Save
    Then a success toast notification should be displayed
    And the profile photo is updated in the application header

  @regression
  Scenario Outline: File size boundary validation
    Given the user navigates to the Profile Photo section
    When the user attempts to upload a file of <size> bytes
    Then <outcome>
    Examples:
      | size      | outcome                             |
      | 5242880   | the file is accepted                |
      | 5242881   | an error toast should be displayed  |
```

### Step 2.3 — Validate and attach

`validate_gherkin_content()` checks structure, tags, scenario count, and navigation steps. Only after explicit user confirmation does the agent call `attach_gherkin_to_feature()`.

### What appears in ADO

File `11000_user-profile-management_regression.feature` attached to Feature #11000 under Attachments.

---

## Phase 3 — Playwright Code Generation (`qa-playwright-generator`)

### Step 3.0 — Live browser inspection

The Playwright MCP server drives the live app. The coding agent builds a `context_map` from live AX tree snapshots and passes it to `generate_playwright_code`. Every selector is validated against the live DOM before entering `locators.ts` — the **zero-hallucination guarantee**.

```
browser_navigate → https://your-app.com/profile
browser_snapshot → AX tree of the profile page → context_map
```

### Step 3.1 — Scaffold healing infrastructure (once per project)

`scaffold_locator_repository()` generates five shared TypeScript infrastructure files:

| File | Purpose |
|---|---|
| `LocatorHealer.ts` | 8-strategy locator resolution chain |
| `LocatorRepository.ts` | Persistent state store for all healing layers |
| `TimingHealer.ts` | Network drift detection and auto-healing |
| `VisualIntentChecker.ts` | Element screenshot comparison |
| `HealingDashboard.ts` | HTTP review server at `http://localhost:7890` |

### Step 3.2 — Generate page object and step definitions

`generate_playwright_code()` produces four files per feature. Each locator entry records selector, intent, stability score, `cdpSignals`, and `visualIntent`:

```typescript
// CDP: stability=100 strategy=data-testid
saveButton: {
  selector: "[data-testid='profile-save-btn']",
  intent: 'save changes button',
  visualIntent: true,
  cdpSignals: { stability: 100, strategy: 'data-testid' }
},
```

### Step 3.3 — Write files to Helix-QA (Agent 4)

`write_helix_files()` routes each generated file to its correct Helix-QA location:

| Generated File | Helix-QA Path |
|---|---|
| `locators.ts` | `src/locators/<kebab>.locators.ts` |
| `<Page>.page.ts` | `src/pages/<Page>.page.ts` |
| `<feature>.steps.ts` | `src/test/steps/<feature>.steps.ts` |
| Infrastructure files | `src/utils/locators/<file>` |

`list_helix_tree` and `read_helix_file` are called first for overlap detection — no file is blindly overwritten.

### Step 3.4 — Attach to ADO

After explicit confirmation, `attach_code_to_work_item()` uploads delta files to PBI #12345. Only net-new files are uploaded.

---

## Phase 4 — Running the Tests

```bash
ENABLE_SELF_HEALING=true \
HEALING_DASHBOARD_PORT=7890 \
cucumber-js --config=config/cucumber.js -p user_profile_photo_management
```

**First run:** `locator-repository.json` does not exist. Every locator works through the full 8-strategy resolution chain, bounding boxes are captured after each successful action, and visual baselines are created.

**Subsequent runs:** Cached healed selectors are tried first (Strategy 1), skipping the rest of the chain. The suite runs significantly faster once baselines are established.

---

## Self-Healing in Action

### Scenario A — When a selector breaks

A developer renames `data-testid="profile-save-btn"` to `data-testid="save-profile-button"`:

1. Strategy 1 (cached) — no cached entry, fails
2. Strategy 2 (`[data-testid='profile-save-btn']`) — element not found, fails
3. Strategy 3 (`page.getByRole('button', { name: /save/i })`) — **succeeds**
4. Suggestion queued to HealingDashboard at `http://localhost:7890`
5. Engineer reviews: current selector, suggested fix, strategy used. Approves or rejects. Nothing commits without review.

### Scenario B — When an API slows down

A backend change causes the upload endpoint to take 1200ms instead of the baseline 430ms.

`TimingHealer` detects 179% drift, auto-adjusts the timeout to 1800ms (1200ms × 1.5 headroom) so the test does not fail, and queues a timing suggestion for review.

### Scenario C — When a visual element changes

A design update changes the success toast from green to teal. `LocatorHealer` still finds the element, but `VisualIntentChecker` detects a 3.2% pixel diff (above 0.5% threshold) and queues a visual suggestion with a before/after diff for engineer review.

---

## What the Engineer Reviews at the End

After one session:

- Structured test cases linked to the PBI in ADO
- A validated `.feature` file attached to the Feature in ADO
- Playwright TypeScript code attached to the PBI in ADO
- A running test suite with three-layer self-healing active
- `http://localhost:7890` for reviewing any AI-suggested changes before they commit

**Nothing is committed to the repository without human review. The system suggests; engineers decide.**

---

## Related

- [QUICKSTART-ADO.md](QUICKSTART-ADO.md) — quick install reference
- [ARCHITECTURE-ADO.md](ARCHITECTURE-ADO.md) — technical architecture
- [WALKTHROUGH-JIRA.md](WALKTHROUGH-JIRA.md) — Jira Cloud walkthrough