# STLC Agents — End-to-End Walkthrough: Jira Cloud

> Jira Cloud pipeline: issue → test cases → Gherkin → Playwright TypeScript → Helix-QA.
> For the Azure DevOps pipeline see [WALKTHROUGH-ADO.md](WALKTHROUGH-ADO.md).

---

## Overview

The Jira pipeline mirrors the ADO pipeline exactly. `qa-jira-manager` replaces `qa-test-case-manager` as the entry point; the three shared agents (`qa-gherkin-generator`, `qa-playwright-generator`, `qa-helix-writer`) run identically in both pipelines.

The same example is used as the ADO walkthrough — **User Profile Photo Management** — to make comparison straightforward.

---

## Setup

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

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

```env
JIRA_CLIENT_ID=your-atlassian-oauth-client-id
JIRA_CLIENT_SECRET=your-atlassian-oauth-client-secret
JIRA_CLOUD_ID=your-atlassian-cloud-id
APP_BASE_URL=https://your-app.example.com
APP_EMAIL=your-test-email@example.com
APP_PASSWORD=your-test-password
```

First run opens a browser once for Jira sign-in. The token is cached at `~/.jira-cache/jira-token.json` and silently refreshed for approximately 60 days.

---

## Phase 1 — Fetch Issue and Generate Test Cases (`qa-jira-manager`)

### What you say

> "Run the full STLC pipeline for Jira issue PROJ-123"

or step by step:

> "Fetch Jira issue PROJ-123 and generate test cases"

### Step 1.1 — Fetch the Jira issue

`fetch_jira_issue(issue_key="PROJ-123")` calls Jira REST API v3, extracts acceptance criteria from the issue description, and runs coverage hint extraction across 11 categories. For this example the response flags:

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

The full response includes: `summary`, `description`, `acceptance_criteria`, `status`, `priority`, `story_points`, `project_key`, `epic_key`, `existing_test_cases_count`, `coverage_hints`.

### Step 1.2 — Deduplication gate

`get_linked_test_cases(issue_key="PROJ-123")` fetches existing `is tested by` linked test cases. The agent diffs by summary and only creates net-new cases.

### Step 1.3 — Generate and confirm

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

The agent proposes the test case list and waits for explicit confirmation before calling `create_and_link_test_cases()`. Steps are stored as ADF tables — no Xray required.

### What appears in Jira

- 8 test case issues created in the same Jira project
- Each issue linked to PROJ-123 via `is tested by`
- Steps visible as a formatted table in the issue description
- Priority, labels, and epic link inherited from the source issue

---

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

### What you say

> "Generate a Gherkin regression suite for PROJ-123"

### Step 2.1 — Source acceptance criteria

The agent uses `acceptance_criteria` from Phase 1 — no second network call if run in the same session. For Epic-level generation, `fetch_jira_epic_hierarchy` returns all child issues and their AC.

### Step 2.2 — Generate the feature file

Same skill rules as the ADO pipeline:

- 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 the user is logged in and navigates to the Profile Settings page

  @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 deliver

`validate_gherkin_content()` checks structure, tags, scenario count, and navigation steps. The agent then asks: **save locally, or attach to the Jira issue?** This is an explicit, independent decision — the agent never infers the delivery target.

---

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

### Step 3.0 — Live browser inspection

Identical to the ADO pipeline. `browser_navigate` + `browser_snapshot` build a `context_map` from the live AX tree. `generate_playwright_code` hard-blocks if `context_map` is absent — 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: `LocatorHealer.ts`, `LocatorRepository.ts`, `TimingHealer.ts`, `VisualIntentChecker.ts`, `HealingDashboard.ts`. This is done once per project and is shared between ADO and Jira pipelines.

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

`generate_playwright_code()` produces four files per feature with AX-tree-verified selectors, stability scores, and `cdpSignals` metadata. Same output format as the ADO pipeline.

### Step 3.3 — Deliver

The agent asks: **attach to the Jira issue, or save locally?** This is a separate, explicit decision from the Gherkin delivery in Phase 2.

---

## Phase 4 — Write to Helix-QA (`qa-helix-writer`)

### What you say

> "Write the generated files to my Helix-QA project at /workspace/my-qa-project"

### What happens

`write_helix_files()` routes each generated file to its correct Helix-QA location. `list_helix_tree` and `read_helix_file` are called first for overlap detection — no file is blindly overwritten.

| 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` |
| `<feature>.feature` | `src/test/features/<feature>.feature` |
| Infrastructure files | `src/utils/locators/<file>` |

---

## Phase 5 — 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, and visual baselines are created.

**Subsequent runs:** Cached healed selectors are tried first (Strategy 1), skipping the rest of the chain.

---

## Self-Healing in Action

Self-healing behaviour is identical between ADO and Jira pipelines — it operates entirely at test runtime, independently of how the tests were generated.

### 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 (primary CSS) — element not found, fails
3. Strategy 3 (`page.getByRole('button', { name: /save/i })`) — **succeeds**
4. Suggestion queued to `http://localhost:7890`
5. Engineer reviews and approves. Nothing commits without review.

### Scenario B — When an API slows down

`TimingHealer` detects drift beyond 20% threshold, auto-adjusts the timeout with 50% headroom, and queues a timing suggestion for review.

### Scenario C — When a visual element changes

`VisualIntentChecker` detects a pixel diff above the 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:

- Jira test case issues linked to the source story with structured steps
- A validated `.feature` file (saved locally or attached to the Jira issue)
- Playwright TypeScript code in the Helix-QA project
- 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-JIRA.md](QUICKSTART-JIRA.md) — quick install reference
- [ARCHITECTURE-JIRA.md](ARCHITECTURE-JIRA.md) — technical architecture
- [WALKTHROUGH-ADO.md](WALKTHROUGH-ADO.md) — Azure DevOps walkthrough