# Tests enregistrés

> Source : https://astrallab.dev/fr/docs/saved-tests

Un parcours qu’un agent a testé peut être conservé comme test enregistré : un script plus quelques détails (nom, ticket, environnement, identifiants utilisés, mode d’enregistrement). N’importe quel agent peut le rejouer, vous pouvez le regarder, et la CI peut l’exécuter.

## Où vivent les tests

- Les **tests de projet** sont enregistrés dans `.astral/tests/<id>.astral.js` à l’intérieur de votre projet et versionnés avec votre dépôt. L’identifiant est un slug du nom du test.
- Les **tests temporaires** sont conservés dans le dossier de données d’Astral et expirent au bout de quelques jours (7 par défaut).

L’agent en enregistre un avec `test_save` et peut le lier à un ticket. Un test enregistré rejoue le script, pas le modèle : une relecture ne consomme donc aucun jeton du modèle et exécute les mêmes étapes à chaque fois.

```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

Le fichier `.astral/config.json` du projet déclare les environnements sur lesquels vos tests s’exécutent et les identifiants qu’ils peuvent utiliser, **par nom**. Les tests naviguent avec `astral.url('/login')`, de sorte que le même test s’exécute en local, en staging ou en production.

```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" }
    }
  }
}
```

| Clé | Ce que c’est |
| --- | --- |
| `envs` | Des URL de base nommées. `protected: true` marque un environnement tel que la production. Pas de nom d’utilisateur ni de mot de passe dans l’URL. |
| `defaultEnv` | L’environnement utilisé lorsqu’aucun n’est indiqué. |
| `collections` | Des tests exécutés dans l’ordre comme un groupe, avec un résumé de réussite ou d’échec et un rapport reliant celui de chaque test. |
| `credentials` | Des connexions nommées : un nom d’utilisateur, un mot de passe, une graine de code à usage unique et des champs supplémentaires. Les secrets sont des références, jamais des valeurs. |
| `layout` | Les sélecteurs que la vérification de la mise en page ignore, et ses seuils. |

## Identifiants et trousseau

Un secret dans `config.json` est une référence vers l’endroit où il se trouve, jamais la valeur. Un mot de passe en clair dans le fichier est rejeté. Une référence est de l’un de ces types :

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

| Référence | Où se trouve la valeur |
| --- | --- |
| `keychain` | Le trousseau de votre système. Vous le définissez dans Astral ; un agent ne peut jamais le relire. |
| `env` | Une variable d’environnement dont le nom commence par `ASTRAL_TEST_`. |
| `local` | `.astral/secrets.local.json`, qui doit figurer dans `.gitignore`. Astral refuse de le créer dans le cas contraire et avertit s’il existe déjà sans être ignoré. |

- L’agent ne voit jamais que le nom de l’identifiant et le nom d’utilisateur. `astral.fill` résout lui-même la valeur et la saisit avec de vraies frappes de touches ; l’agent apprend seulement qu’elle a été saisie et masquée.
- Un secret n’est saisi que dans un champ sensible (mot de passe, code à usage unique, carte) sur l’origine propre de l’environnement, de sorte qu’il ne peut être ni relu ni envoyé à un autre site. Les rapports affichent •••••• à sa place.
- Un secret du trousseau est stocké avec les origines des environnements à ce moment-là et n’est saisi que sur celles-ci, même si `config.json` est modifié ensuite. Pour les connexions sensibles, préférez le trousseau.

## Environnements protégés

Sur un environnement marqué `protected` (la production, par exemple), seuls les tests déclarés `readOnly` s’exécutent, et seulement après qu’une personne a approuvé dans Astral cette version exacte du test. Un agent peut demander `readOnly: true`, mais c’est une demande, pas une approbation : vous l’approuvez avec **Approve as read-only** dans le panneau Tests, l’approbation est conservée en dehors du projet, et elle est perdue si le test est modifié. Dans une collection, les tests non approuvés sont ignorés, avec la raison.

## Viewports

Un test ou une collection peut s’exécuter sur un ou plusieurs viewports, et Astral exécute chaque test sur chacun d’eux.

| Préréglage | Taille (px CSS) | Densité de pixels | Tactile |
| --- | --- | --- | --- |
| `mobile` | 390 × 844 | 3   | oui |
| `tablet` | 820 × 1180 | 2   | oui |
| `desktop` | 1440 × 900 | 1   | non |

Un viewport personnalisé a une largeur et une hauteur de 200 à 4096 px, et éventuellement une densité de pixels, le tactile, un user agent et un nom. Dans Astral, le panneau de l’onglet est redimensionné au viewport pour l’exécution puis retrouve sa propre taille ; la densité de pixels, le tactile et le user agent n’y sont pas émulés, et l’exécution le signale. Le runner headless avec Chrome les émule tous.

## La vérification de la mise en page

La vérification de la mise en page examine la page telle qu’elle est rendue et signale des constats, chacun avec une règle, une gravité, un sélecteur, un rectangle, un message et un correctif CSS suggéré.

| Règle | Ce qu’elle détecte |
| --- | --- |
| `horizontal-overflow` | La page est plus large que le viewport ; elle nomme l’élément qui dépasse. |
| `overlap` | Du texte ou des contrôles visibles qui se chevauchent. |
| `text-clipped` | Du texte coupé par un débordement, ou un mot long qui sort de sa boîte. |
| `offscreen` | Un contrôle en dehors du viewport horizontal. |
| `tap-target` | Une cible tactile de moins de 24 × 24 px est une erreur ; de moins de 44 × 44, un avertissement. Viewports tactiles uniquement. |
| `small-text` | Du texte de moins de 12 px sur des écrans jusqu’à 600 px de large. |

Trois façons de l’utiliser :

- L’outil [`layout_check`](https://astrallab.dev/fr/docs/tools.md#tool-layout_check) : l’agent trouve un problème, corrige le CSS et vérifie à nouveau.
- `astral.expect.layout()` comme étape d’un test.
- `layoutCheck: true` sur un test ou une collection, pour ajouter une vérification à la fin de chaque exécution par viewport.

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

Avec une capture d’écran, la page est capturée avec chaque constat entouré. Sur un moteur qui ne calcule pas la mise en page, la vérification est signalée comme ignorée, jamais comme réussie.

## Relecture avec Play

L’agent appelle `test_open_in_astral` et Astral ouvre son panneau Tests avec le test chargé et en pause. Vous appuyez sur **Play** pour le regarder s’exécuter : ralenti, pause, pas à pas et arrêt. Par défaut, l’agent ne peut pas le démarrer : Play est aussi un contrôle de sécurité. Pour les démos et les revues que vous lui avez demandé de piloter, l’agent peut le démarrer avec `play: true` ; cela exige la même permission que `test_run`, ne fonctionne que pour les tests enregistrés dans un projet que vous avez autorisé, et vous gardez Pause, Step et Stop.