---
name: install-jira-trigger
description: Installa in locale l'handler del link "artemest-test://" (Mac o Windows) che permette di lanciare i test Playwright da un link Jira. Usa quando un collega deve configurare/installare il trigger dei test da Jira su questa macchina, o dice "installa il trigger Jira", "setup del link dei test", "install jira trigger".
---

# Installazione del trigger test da Jira (`artemest-test://`)

Obiettivo: sulla macchina di chi invoca questa skill, registrare l'handler del
protocollo `artemest-test://` così che un link su Jira (o su artemest-hub/vtool)
lanci **in locale** un test Playwright e ne apra il report. L'esecuzione locale
usa un IP "umano", quindi **anche i test di login OAuth passano** (sui runner
GitHub Cloudflare li blocca — vedi README del repo).

Segui i passi nell'ordine. Riporta all'utente cosa fai e l'esito di ogni verifica.

## 0. Individua il repo e l'OS

1. Assicurati di essere nella root del repo `artemest-storefront-tests` (deve
   esistere `playwright.config.ts` e la cartella `tests/`). Se non ci sei,
   chiedi all'utente il percorso.
2. Rileva l'OS: macOS oppure Windows. I passi divergono da qui.

## 1. Prerequisiti (comune a entrambi gli OS)

1. Se manca `node_modules/`, esegui `npm ci`.
2. Installa il browser headless:
   `npx playwright install chromium-headless-shell`
   - **Se si blocca in estrazione** (scarica al 100% poi resta fermo, la cartella
     `chromium_headless_shell-*` resta con soli 2 file ABOUT/LICENSE): è un
     deadlock noto. Applica il workaround: termina i processi
     `playwright install`/`oopDownloadBrowserMain`, rimuovi
     `~/Library/Caches/ms-playwright/__dirlock` (Mac) o
     `%USERPROFILE%\AppData\Local\ms-playwright\__dirlock` (Win), poi scarica lo
     zip del build a mano (URL dal log di install) e scompattalo nella cache. Su
     Mac vedi la memoria `playwright-install-deadlock-workaround`.
3. I test di **login** richiedono un file `.env` con `MAILOSAUR_API_KEY`,
   `MAILOSAUR_SERVER_ID`, `MAILOSAUR_INBOX_ID`. Se assente, avvisa che i login
   non gireranno finché non lo si crea (gli altri 3 spec funzionano lo stesso).

## 2a. macOS

1. Registra il path del repo (per l'handler): dalla root del repo,
   `echo "$(pwd)" > ~/.artemest-test.conf`
2. Costruisci e registra l'handler:
   `./tools/jira-trigger/build.sh`
   (compila `handler.applescript` in `~/Applications/ArtemestTestTrigger.app`,
   registra lo schema URL, rende eseguibili `run-jira-test.sh` e `launch.command`).
   Nota: l'handler apre `launch.command` con `open` e **non** pilota Terminal via
   AppleScript, quindi non serve il permesso di Automazione (TCC).
3. Verifica lo schema: `open "artemest-test://run?spec=cyc-currency&env=staging"`
   Poi controlla che parta il runner:
   `pgrep -fl "playwright test cyc-currency"` entro ~40s. Deve comparire una
   finestra Terminal col test; a fine run si apre il report su `localhost:9323`.

## 2b. Windows (PowerShell)

Esegui i comandi in PowerShell.

1. Registra l'handler e il path del repo (dalla root del repo):
   `powershell -ExecutionPolicy Bypass -File .\tools\jira-trigger\windows\register.ps1`
   (crea `HKCU\Software\Classes\artemest-test\shell\open\command` → `handler.ps1`,
   e salva il path in `%USERPROFILE%\.artemest-test.conf`).
2. Verifica la chiave:
   `Get-ItemProperty 'HKCU:\Software\Classes\artemest-test\shell\open\command'`
3. Verifica lo schema:
   `Start-Process "artemest-test://run?spec=cyc-currency&env=staging"`
   Deve aprirsi una nuova finestra PowerShell col test; a fine run si apre il
   report nel browser. L'handler valida `spec`/`env` contro la whitelist e lancia
   `scripts\run-jira-test.ps1`.

## 3. Formato del link (per Jira)

```
artemest-test://run?spec=<SPEC>&env=<staging|prod>&jira=<CHIAVE-ISSUE>
```
- `spec` ∈ { `cyc-currency`, `text-search-fayt-plus`, `Trade-form-it-us`,
  `login-B2B-hara`, `new-b2c-login-us-gb` }
- `env` = `staging` (default) o `prod`; `jira` è solo etichetta (facoltativa).

Su un'issue Jira: **Aggiungi → Collegamento web** con l'URL sopra. Al primo click
il browser chiede conferma per aprire l'app esterna (una volta per browser).

## 4. Verifica finale end-to-end

Fai partire un test **non-login** (non serve Mailosaur), es. `cyc-currency` su
staging, tramite il link, e conferma che: (a) parte il processo di test, (b) a
fine run si apre il report HTML. Riporta pass/fail all'utente.

## Troubleshooting

- **Mac, "app non verificata" (Gatekeeper):** l'app è compilata in locale, non è
  in quarantena; se comparisse il blocco, autorizzala una volta da Impostazioni →
  Privacy e sicurezza.
- **Windows, ExecutionPolicy:** usa sempre `-ExecutionPolicy Bypass` come nei
  comandi sopra; non serve cambiare la policy di sistema.
- **Test falliscono in ~2ms con "browserType.launch ... Executable doesn't exist":**
  manca `chrome-headless-shell` → rifai il passo 1.2 (occhio al deadlock).
- **Il link non fa nulla:** verifica che lo schema sia registrato (Mac:
  `lsregister -dump | grep artemest-test`; Win: la chiave HKCU del passo 2b.2) e
  che `~/.artemest-test.conf` punti alla root corretta del repo.