# Esecuzioni di test

> Fonte: https://astrallab.dev/it/docs/test-runs

Un’esecuzione di test trasforma uno script in prove. L’agente avvolge un flusso in `astral.test`, lo divide in passaggi, dichiara cosa deve essere vero, e Astral registra ciò che è accaduto.

Le esecuzioni di test usano lo strumento `run_script`, che esegue JavaScript scritto dall’agente in una sandbox che chiama gli altri strumenti. Il gruppo `script` è disattivato per impostazione predefinita; il gruppo `tests` è attivo per impostazione predefinita, ma ha effetto solo finché `script` è attivo. Vedi [il gruppo script](https://astrallab.dev/it/docs/tools.md#group-script).

## Un esempio

```js
return await astral.test('Login demo', async () => {
  await astral.step('Open the store', () => astral.navigate({url: 'http://localhost:3000/'}));
  await astral.step('Sign in', async () => {
    await astral.type({locator: {role: 'textbox', name: 'Username'}, text: 'demo'});
    await astral.type({locator: {role: 'textbox', name: 'Password'}, text: 'demo', submit: true});
    await astral.expect.visible({role: 'button', name: 'Sign out'});
    await astral.expect.noErrors();
  });
  await astral.step('Pay', async () => {
    await astral.click({locator: {role: 'button', name: 'Pay'}});
    await astral.expect.request({urlContains: '/api/', method: 'POST', status: '2xx'});
  });
}, {continueOnFailure: true, record: 'actions'});
```

Dai a `run_script` un `timeoutMs` da 60000 a 120000 per un test: le prove richiedono tempo.

## astral.test e astral.step

Opzioni di `astral.test(name, fn, options)`: `tabId`, `continueOnFailure` (predefinito false) e `record`. Non lancia un’eccezione quando un passaggio fallisce: controlla lo `status` nel risultato, che contiene anche i totali, un `summary` in Markdown e i percorsi del report.

`astral.step(name, fn)` raggruppa azioni. Alla fine, e sempre in caso di errore, Astral salva uno screenshot, l’URL e il titolo, le richieste effettuate durante il passaggio (quelle fallite con intestazioni e corpi oscurati), errori e avvisi della console ed eventuali nuovi gruppi di errori. Un passaggio fallisce quando la sua funzione lancia un’eccezione o una aspettativa al suo interno fallisce. Senza `continueOnFailure` il test si ferma al primo passaggio fallito.

`run_script` accetta anche `test: {name, continueOnFailure, ...}` per trattare l’intero script come un unico test.

## Aspettative

| Chiamata | Passa quando |
| --- | --- |
| `expect.visible(locator)` | L’elemento è visibile, attendendo fino a `timeoutMs` (predefinito 5000). |
| `expect.hidden(locator)` | L’elemento non è visibile. |
| `expect.text(locator, 'contains')` / `expect.text('text')` | L’elemento contiene il testo, o il testo compare in un punto qualsiasi della pagina. |
| `expect.url('/dashboard')` / `expect.url(/regex/)` | L’URL della scheda corrisponde. |
| `expect.request({urlContains, method, status})` | È stata effettuata una richiesta corrispondente dall’inizio del passaggio. `status` è un numero, `'2xx'` o `'error'`. |
| `expect.noErrors({kinds, waitMs, ignoreStatus, ignore})` | Dall’inizio del passaggio non è comparso alcun nuovo gruppo di errori. Ignora stati come 401 o messaggi per sottostringa. |
| `expect.layout({rules, ignore})` | Il layout responsive della pagina non ha errori al viewport dell’esecuzione. Vedi [il controllo del layout](https://astrallab.dev/it/docs/saved-tests.md#layout). |

Un localizzatore è `{role, name, text, nth, exact}`, un riferimento di snapshot come `"e12"`, oppure un testo. Un’aspettativa fallita lancia un errore di asserzione con ciò che era atteso e ciò che è stato trovato, e il report lo mostra. `astral.screenshot({name, fullPage})` dentro un test aggiunge uno screenshot con nome al passaggio corrente.

## Modalità di registrazione

| Modalità | Cosa viene catturato |
| --- | --- |
| `'off'` | Screenshot solo dei fallimenti. |
| `'steps'` (predefinita) | Uno screenshot alla fine di ogni passaggio. |
| `'actions'` | Anche uno dopo ogni clic, digitazione, selezione, pressione di tasto e navigazione, scattato mentre un indicatore mostra il bersaglio: un riquadro, un’onda nel punto del clic e una didascalia come _click "Sign in"_. |
| `'video'` | Anche fotogrammi della scheda a 4 al secondo (fino a 5 minuti o 200 MB), salvati come `recording.png` animato, e `recording.mp4` dove Astral può codificarne uno (macOS), con un lettore di fotogrammi nel report. |

Gli indicatori sono disegnati in ogni modalità tranne `'off'`, scompaiono dopo 2,5 secondi e alla fine dell’esecuzione, e non intercettano mai i clic. Il testo digitato in un campo password, codice monouso o carta non viene mai scritto: le didascalie mostrano •••••• e il valore è mascherato ovunque nel resto del report. Vedi [Piattaforme](https://astrallab.dev/it/docs/platforms.md) per il supporto video.

## Cosa lascia un’esecuzione

Ogni esecuzione scrive una cartella nella directory dei dati di Astral contenente:

- `report.html`: un report leggibile con un riepilogo, una scheda per passaggio con i suoi screenshot, l’asserzione fallita, le richieste fallite, gli errori della console, gli errori di pagina raggruppati, una timeline delle azioni e una sezione sulle prestazioni.
- `report.json`: gli stessi dati, più un riepilogo in Markdown scritto per essere incollato in una issue.
- Gli screenshot come file PNG e la registrazione, se l’hai richiesta.

Vengono conservate le 50 esecuzioni più recenti (configurabile in Settings → Developer, dove le esecuzioni di test si possono anche disattivare). L’agente rilegge le esecuzioni con `test_runs_list` e `test_run_get`.

## Prove per i ticket

Il riepilogo in Markdown è pensato per essere incollato in una issue, accanto agli screenshot e al report. Se il tuo agente è collegato al tuo strumento di ticket, può pubblicare lì quelle prove per te. Astral in sé non si integra con nessuno strumento di ticket: scrive le prove e lascia la pubblicazione a te o al tuo agente.

I nomi dei test, i passaggi, i nomi degli screenshot e tutto ciò che Astral scrive su un’esecuzione sono in inglese, qualunque sia la lingua che usi tu, il ticket o la pagina. Solo i localizzatori mantengono il testo proprio della pagina.