# Test salvati

> Fonte: https://astrallab.dev/it/docs/saved-tests

Un flusso che un agente ha testato può essere conservato come test salvato: uno script più alcuni dettagli (nome, ticket, ambiente, credenziali usate, modalità di registrazione). Qualsiasi agente può riprodurlo, tu puoi guardarlo e la CI può eseguirlo.

## Dove vivono i test

- I **test di progetto** sono salvati in `.astral/tests/<id>.astral.js` all’interno del tuo progetto e versionati con il tuo repository. L’id è uno slug del nome del test.
- I **test temporanei** sono conservati nella cartella dei dati di Astral e scadono dopo un certo numero di giorni (7 per impostazione predefinita).

L’agente ne salva uno con `test_save` e può collegarlo a un ticket. Un test salvato riproduce lo script, non il modello, quindi una riproduzione non consuma token del modello ed esegue gli stessi passaggi ogni volta.

```js
return await astral.test('Login', async () => {
  await astral.step('Open the login page', () => astral.navigate({url: astral.url('/login')}));
  await astral.step('Sign in', async () => {
    await astral.fill({locator: {role: 'textbox', name: 'Email'}, credential: 'shop.demo', field: 'username'});
    await astral.fill({locator: {role: 'textbox', name: 'Password', exact: true}, credential: 'shop.demo', field: 'password'});
    await astral.click({locator: {role: 'button', name: 'Sign in'}});
    await astral.expect.url('/account');
  });
}, {record: 'actions'});
```

## .astral/config.json

Il file `.astral/config.json` del progetto dichiara gli ambienti su cui girano i tuoi test e le credenziali che possono usare, **per nome**. I test navigano con `astral.url('/login')`, così lo stesso test gira su locale, staging o produzione.

```json
{
  "project": "shop",
  "envs": {
    "local":   { "baseUrl": "http://localhost:3000" },
    "staging": { "baseUrl": "https://staging.example.com" },
    "prod":    { "baseUrl": "https://www.example.com", "protected": true }
  },
  "defaultEnv": "local",
  "collections": {
    "smoke": { "name": "Smoke", "tests": ["login", "checkout"] }
  },
  "credentials": {
    "shop.demo": {
      "username": "demo@example.com",
      "password": { "keychain": "shop.demo.password" }
    }
  }
}
```

| Chiave | Cos’è |
| --- | --- |
| `envs` | URL di base con nome. `protected: true` contrassegna un ambiente come la produzione. Nessun nome utente o password nell’URL. |
| `defaultEnv` | L’ambiente usato quando non ne viene indicato nessuno. |
| `collections` | Test eseguiti in ordine come un unico gruppo, con un riepilogo di riuscita o fallimento e un report che collega quello di ciascun test. |
| `credentials` | Login con nome: un nome utente, una password, un seme per codici monouso e campi extra. I segreti sono riferimenti, mai valori. |
| `layout` | I selettori che il controllo del layout ignora e le sue soglie. |

## Credenziali e portachiavi

Un segreto in `config.json` è un riferimento a dove si trova, mai il valore. Una password in chiaro nel file viene rifiutata. Un riferimento è uno di questi:

```
{ "keychain": "<id>" }
{ "env": "ASTRAL_TEST_<NAME>" }
{ "local": "<key>" }
```

| Riferimento | Dove si trova il valore |
| --- | --- |
| `keychain` | Il portachiavi del tuo sistema. Lo imposti in Astral; un agente non può mai rileggerlo. |
| `env` | Una variabile d’ambiente il cui nome inizia con `ASTRAL_TEST_`. |
| `local` | `.astral/secrets.local.json`, che deve essere in `.gitignore`. Altrimenti Astral rifiuta di crearlo e avvisa se esiste già senza essere ignorato. |

- L’agente vede solo il nome della credenziale e il nome utente. `astral.fill` risolve il valore da sé e lo digita con vere pressioni di tasti; l’agente sa solo che è stato digitato e mascherato.
- Un segreto viene digitato solo in un campo sensibile (password, codice monouso, carta) sull’origin dell’ambiente stesso, così non può essere riletto né inviato a un altro sito. I report mostrano •••••• al suo posto.
- Un segreto del portachiavi viene memorizzato insieme agli origin degli ambienti in quel momento e digitato solo su quelli, anche se `config.json` viene modificato in seguito. Per i login sensibili, preferisci il portachiavi.

## Ambienti protetti

In un ambiente contrassegnato `protected` (la produzione, per esempio) girano solo i test dichiarati `readOnly`, e solo dopo che una persona ha approvato in Astral quella esatta versione del test. Un agente può chiedere `readOnly: true`, ma è una richiesta, non un’approvazione: la approvi tu con **Approve as read-only** nel pannello Tests, l’approvazione è conservata fuori dal progetto e va persa se il test viene modificato. In una collezione, i test non approvati vengono saltati con il motivo.

## Viewport

Un test o una collezione può girare su uno o più viewport, e Astral esegue ogni test su ciascuno.

| Preset | Dimensione (px CSS) | Densità di pixel | Touch |
| --- | --- | --- | --- |
| `mobile` | 390 × 844 | 3   | sì  |
| `tablet` | 820 × 1180 | 2   | sì  |
| `desktop` | 1440 × 900 | 1   | no  |

Un viewport personalizzato ha una larghezza e un’altezza da 200 a 4096 px, e facoltativamente una densità di pixel, il touch, uno user agent e un nome. Dentro Astral il pannello della scheda viene ridimensionato al viewport per l’esecuzione e poi torna alla sua dimensione; densità di pixel, touch e user agent non vengono emulati lì, e l’esecuzione lo segnala. Il runner headless con Chrome li emula tutti.

## Il controllo del layout

Il controllo del layout esamina la pagina così come viene renderizzata e segnala dei rilievi, ciascuno con una regola, una gravità, un selettore, un rettangolo, un messaggio e una correzione CSS suggerita.

| Regola | Cosa trova |
| --- | --- |
| `horizontal-overflow` | La pagina è più larga del viewport; indica l’elemento che sporge. |
| `overlap` | Testo o controlli visibili uno sopra l’altro. |
| `text-clipped` | Testo tagliato da un overflow, o una parola lunga che esce dalla sua casella. |
| `offscreen` | Un controllo fuori dal viewport orizzontale. |
| `tap-target` | Un bersaglio touch sotto 24 × 24 px è un errore; sotto 44 × 44, un avviso. Solo viewport touch. |
| `small-text` | Testo sotto i 12 px su schermi fino a 600 px di larghezza. |

Tre modi per usarlo:

- Lo strumento [`layout_check`](https://astrallab.dev/it/docs/tools.md#tool-layout_check): l’agente trova un problema, corregge il CSS e ricontrolla.
- `astral.expect.layout()` come passaggio di un test.
- `layoutCheck: true` su un test o una collezione, per aggiungere un controllo alla fine di ogni esecuzione per viewport.

```json
{
  "collections": {
    "rwd": { "name": "Responsive", "tests": ["home", "checkout"], "viewports": ["mobile", "tablet", "desktop"], "layoutCheck": true }
  },
  "layout": { "ignore": [".chat-widget", "#cookie-banner"] }
}
```

Con uno screenshot, la pagina viene catturata con ogni rilievo evidenziato. Su un motore che non calcola il layout delle pagine, il controllo viene segnalato come saltato, mai come superato.

## Riproduzione con Play

L’agente chiama `test_open_in_astral` e Astral apre il suo pannello Tests con il test caricato e in pausa. Premi **Play** per guardarlo girare: rallentatore, pausa, passo passo e stop. Per impostazione predefinita l’agente non può avviarlo: Play è anche un controllo di sicurezza. Per demo e revisioni che gli hai chiesto di condurre, l’agente può avviarlo con `play: true`; richiede lo stesso permesso di `test_run`, funziona solo per test salvati in un progetto che hai consentito, e tu mantieni Pause, Step e Stop.