# looper-dashboard

Generate daily CI dashboards for any QE repository on the [LooperPro](https://looperpro.prod.walmart.com) CI platform.

Supports three test suite types:

| Suite | Report format | Default history |
|---|---|---|
| `karate` | `karate-summary-json.txt` + per-feature detail | 14 days |
| `playwright` | `pw-summary-report.json` | 14 days |
| `playwright-monocart` | `monocart-report/index.html` (zlib-compressed) | 30 days |

---

## Requirements

| Requirement | Why |
|---|---|
| Python 3.11+ | Runtime |
| `mcp-cli` (optional) | Auto-refreshes LooperPro auth tokens |
| `code-puppy` (optional) | Powers the AI failure analysis step |

Authentication is read from `~/.mcp-cli/tokens.json` or `~/.code_puppy/puppy.cfg` automatically — no extra config needed.

---

## Installation

```bash
pip install looper-dashboard
```

Or from the repo:

```bash
pip install ./looper-dashboard
```

---

## Quick Start

### 1. Scaffold a config

```bash
# Creates daily_flows.yml in the current directory
looper-dashboard --init karate
looper-dashboard --init playwright
looper-dashboard --init playwright-monocart
```

Edit the generated file to add your LooperPro job names and flow names.

### 2. Generate the dashboard

```bash
looper-dashboard --suite karate --config daily_flows.yml --open
looper-dashboard --suite playwright --config daily_flows.yml --open
looper-dashboard --suite playwright-monocart --config daily_flows.yml --open
```

### 3. Override the repo SCM URL

```bash
looper-dashboard --suite karate \
  --config daily_flows.yml \
  --scm-url https://gecgithub01.walmart.com/my-org/my-repo.git \
  --open
```

---

## `daily_flows.yml` format

### Karate / Playwright

```yaml
# SCM URL of the repository being monitored
scm_url: https://gecgithub01.walmart.com/my-org/my-repo.git

jobs:

  # LooperPro job name → list of flow names to monitor
  my-org/my-repo-tests:
    - my-flow-dev
    - my-flow-stage
    - my-flow-prod

  my-org/my-repo-health-checks:
    - health-dev
    - health-stage
```

### Playwright-Monocart (with explicit job_ids)

Some repos' jobs cannot be discovered by SCM URL in LooperPro. Add a `job_ids` section with the UUIDs from the LooperPro UI:

```yaml
scm_url: https://gecgithub01.walmart.com/my-org/my-repo.git

# Explicit job IDs (look these up in the LooperPro UI)
job_ids:
  my-monocart-job: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

jobs:

  my-monocart-job:
    - e2e-flow-dev
    - e2e-flow-stage
```

---

## CLI Reference

```
looper-dashboard [OPTIONS]

Options:
  --suite SUITE           Test suite type: karate, playwright, playwright-monocart  [required]
  --config PATH           Path to daily_flows.yml  [required]
  --scm-url URL           Override scm_url from daily_flows.yml
  --output PATH           Output HTML file path (default varies by suite)
  --days N                Days of build history to fetch (default: 14 or 30)
  --open                  Auto-open dashboard in browser when done
  --no-ai                 Skip the AI failure analysis step
  --no-details            Skip fetching test summary details (faster, status only)
  --save-failures PATH    Path to save failures JSON
  --analysis-json PATH    Use a pre-computed AI analysis JSON instead of running live AI
  --init SUITE            Scaffold a starter daily_flows.yml and exit

  -h, --help              Show help and exit
```

---

## AI Analysis

When `--no-ai` is not set, the orchestrator:

1. Saves a `*-failures.json` summary of all failing flows
2. Invokes `code-puppy` to classify each failure as one of:
   - `service_regression` — likely a code regression in the app
   - `environment_issue` — infra/network/auth failure
   - `test_issue` — stale selector or bad test data
   - `flaky` — intermittent, no clear pattern
3. Regenerates the dashboard HTML with an AI analysis panel embedded

If `code-puppy` is not installed, the AI step is skipped gracefully.

---

## Publishing

### To public PyPI

```bash
cd looper-dashboard
pip install hatch
hatch build          # creates dist/looper_dashboard-0.1.0.tar.gz and .whl
hatch publish        # prompts for PyPI API token
```

### To Walmart internal PyPI registry

Add the registry to `~/.config/hatch/config.toml`:

```toml
[publish.index.repos.internal]
url = "https://your-internal-pypi-registry/simple/"
```

Then:

```bash
hatch publish --repo internal
```

---

## Onboarding a new repo

1. Create a `daily_flows.yml` for the target repo (use `--init` to scaffold)
2. Add job and flow names (find them in LooperPro or via `mcp-cli`)
3. Run `looper-dashboard --suite <type> --config daily_flows.yml --open`

No code changes required — the package is entirely configuration-driven.
