Aller au contenu
English

Tester et livrer

  • Leçon 19
  • 55 min
  • Module 6 : Sécurité, accessibilité et remise du travail

Où nous en sommes

Dans les deux dernières leçons, nous avons rendu le bureau sûr et utilisable au clavier et avec un lecteur d'écran. Beaucoup de vérifications réussissent. Mais des vérifications sur des parties isolées ne voient ni la vraie API, ni le navigateur, ni la construction : 75 vérifications ont réussi pendant que le bureau n'affichait rien. Dans cette leçon, nous testons des parties jusqu'à un vrai parcours dans un navigateur, et nous remettons le bureau avec des preuves, comme une voiture testée avant sa vente.

Ce que vous saurez faire

Prouvez que le bureau fonctionne avant de le remettre. Testez chaque partie avec une fausse API. Exécutez aussi un parcours de bout en bout dans un vrai navigateur, sur un écran d’ordinateur et de téléphone. Vérifiez ensuite la construction de production et notez ce dont le prochain développeur aura besoin.

Avant de commencerCe qu’il faut savoir et avoir sous la mainEnviron 55 minutes

Ce que vous devez savoir

Ce qu’il vous faut sur votre ordinateur

  • Le projet après Interactions accessibles : npm test se termine par ℹ pass 27 (27 réussites) et Tests 48 passed (48) (48 tests réussis).
  • Environ 200 Mo d’espace disque libre pour le navigateur que Playwright télécharge, et une connexion réseau pour ce téléchargement.
  • Arrêtez npm run api et npm run dev avant les étapes de bout en bout. Le parcours démarre ses propres serveurs sur les ports 8100 et 4173.

Testé sur macOS (Apple silicon) avec Node.js 24 dans Chromium. Les commandes sont les mêmes sur Windows et Linux, mais elles n’y ont pas été testées. Firefox, Safari et les vrais téléphones ne sont pas testés.

Une usine automobile teste chaque pièce sur un banc : les freins, les phares, le moteur, séparément et plusieurs fois. Ensuite, un conducteur essaie la voiture terminée sur une vraie route. Avant la vente, un inspecteur vérifie les documents, et l’acheteur reçoit un manuel. Aucune vérification ne suffit à elle seule. Un frein parfait sur le banc ne dit rien d’un câble de frein qui n’a jamais été raccordé.

Le problème : 75 vérifications réussissent, et le bureau n’affiche rien

Section intitulée « Le problème : 75 vérifications réussissent, et le bureau n’affiche rien »

Tomás veut que les journaux de l’API indiquent quelle version du bureau a envoyé chaque requête. Il ajoute un en-tête dans src/api/client.ts (une modification construite; ne la gardez pas) :

src/api/client.ts (Tomás's change)
headers: { 'X-Desk-Version': '1.0.0', ...(init.body ? { 'Content-Type': 'application/json' } : {}), ...init.headers },

Il exécute npm test : ℹ pass 27 et Tests 48 passed (48). Toutes les vérifications réussissent. Puis il ouvre le bureau :

La liste des billets avec une boîte d'erreur rouge : le service de billets n'a pas répondu. Vérifiez votre connexion, puis réessayez. En dessous, un bouton pour réessayer. Aucune ligne de billet.
Avec un seul en-tête supplémentaire, tous les tests de composants réussissent, mais le vrai navigateur refuse chaque requête. L’image est en anglais.

La console du navigateur explique pourquoi :

Access to fetch at 'http://127.0.0.1:8396/v1/tickets?limit=50' from origin 'http://localhost:4396' has been blocked by CORS policy: Request header field x-desk-version is not allowed by Access-Control-Allow-Headers in preflight response.

(L’équipe du cours a exécuté le bureau sur d’autres ports; les vôtres sont 8100 et 5173.) Un en-tête personnalisé oblige le navigateur à interroger d’abord l’API avec une requête OPTIONS. C’est une vérification préalable (preflight). L’API simulée n’autorise que trois en-têtes :

Fenêtre de terminal
curl -i -X OPTIONS http://127.0.0.1:8100/v1/tickets -H "Origin: http://localhost:5173" -H "Access-Control-Request-Method: GET" -H "Access-Control-Request-Headers: x-desk-version"
HTTP/1.1 204 No Content
Access-Control-Allow-Origin: http://localhost:5173
Access-Control-Allow-Methods: GET, POST, PATCH
Access-Control-Allow-Headers: Content-Type, Idempotency-Key, X-Request-ID

Alors, pourquoi les 48 tests de composants ont-ils réussi? Parce qu’ils n’utilisent jamais le réseau d’un navigateur. installFakeApi remplace fetch par une fonction qui donne à chaque test la réponse demandée. Il n’y a ni API, ni origine, ni vérification préalable. La fausse API a testé chaque pièce sur le banc, mais le câble entre les pièces n’a jamais été raccordé.

Chaque type de vérification prouve quelque chose que les autres ne peuvent pas prouver :

  • Un test de composant affiche une partie, comme le panneau de brouillon, dans une page simulée (jsdom). Il remplace l’API par une fausse API : un substitut qui renvoie des réponses fixes. Il est rapide et peut créer n’importe quelle situation : une erreur 404, un flux interrompu après deux segments, une réponse lente. Il ne peut pas voir la vraie API, le navigateur ou les fichiers construits.
  • Un test de bout en bout (E2E) exécute le vrai bureau construit dans un vrai navigateur, avec l’API simulée en marche. Il fait ce qu’un utilisateur fait, au clavier. Il voit CORS, les fichiers chargés à la demande, le rythme réel du flux et un écran de taille téléphone. Il est lent. Vous n’en gardez donc que quelques-uns, pour les tâches principales.
  • Les vérifications de construction examinent ce que vous livrez : les types, la construction de production, les secrets et le rapport de taille. Elles ne disent rien du comportement, mais sans elles, vous livrez sans savoir.
Quatre couches empilées, étroites en haut et larges en bas. En haut : avant chaque livraison, npm run check : vérification des types et construction de production en 0,6 s, vérification des secrets et rapport de taille en 0,1 s; prouve que les fichiers se construisent, qu'aucun secret n'est dans dist et que la taille est connue; ne peut pas voir si les écrans fonctionnent. Deuxième couche : bout en bout avec Playwright, 3 parcours sur 2 écrans, 6 tests, environ 27 s, avec la construction de production, l'API simulée et Chromium, au clavier; prouve que les parties fonctionnent ensemble avec de vraies requêtes et un écran de téléphone; ne peut pas voir Firefox, Safari ou un vrai lecteur d'écran. Troisième couche : composants avec Vitest et Testing Library, 48 tests, environ 5 s, chaque partie avec une fausse API; prouve chaque état de chaque partie; ne peut pas voir la vraie API, le navigateur ou la construction. En bas : API simulée et scripts avec node:test, 27 tests, 0,2 s; prouve que l'API d'exercice respecte le contrat. Une note : à la main, une fois par livraison, le clavier et un lecteur d'écran sur les vrais écrans.
Ce que chaque vérification du bureau prouve, son coût et ce qu'elle ne peut pas voir. Beaucoup de vérifications rapides en bas, peu de vérifications lentes en haut.
Description textuelle du diagramme

Le diagramme présente quatre couches empilées, étroites en haut et larges en bas. La couche du haut correspond à la vérification avant chaque livraison, npm run check. La vérification des types et la construction de production prennent 0,6 seconde. La vérification des secrets et le rapport de taille prennent 0,1 seconde. Cette couche prouve que les fichiers se construisent, qu’aucun secret n’est dans dist et quelle est la taille. Elle ne peut pas voir si les écrans fonctionnent. La deuxième couche est le parcours de bout en bout avec Playwright : 3 parcours sur 2 écrans, 6 tests en environ 27 secondes. Elle utilise la construction de production, l’API simulée et Chromium, au clavier. Elle prouve que les parties fonctionnent ensemble, avec de vraies requêtes, CORS et un écran de téléphone. Elle ne peut pas voir Firefox, Safari ou un vrai lecteur d’écran. La troisième couche regroupe les tests de composants avec Vitest et Testing Library : 48 tests en environ 5 secondes. Chaque partie utilise une fausse API. Ces tests prouvent chaque état de chaque partie : chargement, erreur, arrêt, interruption, refus. Ils ne peuvent pas voir la vraie API, le navigateur ou la construction. La couche du bas regroupe les vérifications de l’API simulée et des scripts avec node:test : 27 tests en 0,2 seconde. Elles prouvent que l’API d’exercice respecte le contrat. Une note sous les couches indique qu’une personne vérifie les vrais écrans à la main une fois par livraison. Elle utilise le clavier et un lecteur d’écran.

  • Sans navigateur
  • Un vrai navigateur
Une exécution de chaque vérification sur le portable de l'équipe du cours, avec d'autres tâches en cours. Les 6 tests de bout en bout prennent plus de temps que les 75 autres tests réunis.
Description textuelle du graphique

Un graphique à colonnes montre la durée d’une exécution de chaque vérification, en secondes. Les 27 vérifications de l’API simulée et des scripts prennent 0,2 seconde. Les 48 tests de composants prennent 4,8 secondes. Les vérifications de construction prennent 0,7 seconde : types, construction de production, secrets et rapport de taille. Les 6 tests de bout en bout prennent 26,9 secondes, plus que toutes les autres vérifications réunies. Vos durées seront différentes; la forme restera la même.

Le graphique explique cette forme : une vérification de 27 secondes s’exécute moins souvent qu’une vérification de 5 secondes. Vous testez donc chaque état avec des tests de composants rapides. Vous réservez le parcours de bout en bout à ce que seul un vrai navigateur peut montrer.

Un petit exemple : un test de composant, ligne par ligne

Section intitulée « Un petit exemple : un test de composant, ligne par ligne »

Voici un test du panneau de brouillon de Interactions accessibles. Lisez chaque valeur :

src/features/draft/DraftPanel.test.tsx (one test)
test('a ticket without a draft says so', async () => {
installFakeApi(() => apiError(404, 'no_draft', 'No AI draft exists for this ticket.'));
render(<DraftPanel ticketId="T-30001" onUse={() => {}} />);
await userEvent.click(screen.getByRole('button', { name: 'Write a draft' }));
expect(await screen.findByRole('status')).toHaveTextContent('Write the reply yourself');
});
  1. installFakeApi(…) remplace fetch. Chaque requête reçoit maintenant la réponse 404 avec la structure d’erreur du contrat : le code no_draft.
  2. render(…) affiche le panneau de T-30001 dans jsdom.
  3. getByRole('button', { name: 'Write a draft' }) trouve le bouton comme un lecteur d’écran : par rôle et nom, dans l’arbre d’accessibilité. Si le bouton perdait son nom, le test échouerait.
  4. Le test clique dessus, puis attend l’état, qui doit contenir « Write the reply yourself » (rédigez la réponse vous-même). Ce sont les mots que src/lib/errors.ts donne pour no_draft.

Le test prouve que le panneau transforme une réponse no_draft en mots appropriés. Il ne prouve pas que la vraie API envoie no_draft. C’est le rôle de la vérification propre à l’API simulée : « un billet sans brouillon enregistré donne 404 no_draft ». La fausse API et le contrat sont donc testés des deux côtés du câble. Le parcours de bout en bout vérifie le câble lui-même.

  1. Installez l’exécuteur de tests de Playwright à une version précise :

    Fenêtre de terminal
    npm install --save-dev --save-exact @playwright/test@1.64.0

    npm affiche added 3 packages (3 paquets ajoutés) et found 0 vulnerabilities (aucune vulnérabilité trouvée).

  2. Téléchargez le navigateur que Playwright pilote :

    Fenêtre de terminal
    npx playwright install chromium

    Sur le Mac de l’équipe du cours, la commande a affiché Downloading Chrome for Testing 156.0.8078.4 (playwright chromium v1248) (téléchargement de Chrome pour les tests). Elle a téléchargé 185,8 Mio. Si le navigateur est déjà sur votre ordinateur, la commande se termine immédiatement.

  3. Créez playwright.config.ts dans le dossier du projet. Il démarre l’API simulée avec le petit jeu de données, puis construit et sert les fichiers de production. Ensuite, il exécute chaque test sur un écran d’ordinateur et un écran de téléphone (taille du Pixel 7) :

    playwright.config.ts
    // One end-to-end flow in a real browser, against the production build and the mock API.
    // npx playwright install chromium (once: downloads the browser)
    // npm run test:e2e
    // Ports: E2E_API_PORT (8100) and E2E_WEB_PORT (4173), if those are busy on your computer.
    import { defineConfig, devices } from '@playwright/test';
    const apiPort = Number(process.env.E2E_API_PORT ?? 8100);
    const webPort = Number(process.env.E2E_WEB_PORT ?? 4173);
    const web = `http://localhost:${webPort}`;
    export default defineConfig({
    testDir: 'e2e',
    timeout: 60_000,
    workers: 1,
    retries: 0,
    reporter: [['list']],
    use: { baseURL: web, trace: 'retain-on-failure' },
    projects: [
    { name: 'desktop', use: { ...devices['Desktop Chrome'] } },
    { name: 'phone', use: { ...devices['Pixel 7'] } },
    ],
    webServer: [
    {
    command: `node mock-api/server.mjs --size small --port ${apiPort}`,
    url: `http://127.0.0.1:${apiPort}/health`,
    env: { CORS_ORIGINS: web, MOCK_LOG: '0' },
    reuseExistingServer: false,
    },
    {
    command: `npx vite build && npx vite preview --port ${webPort} --strictPort`,
    url: web,
    env: { VITE_API_URL: `http://127.0.0.1:${apiPort}` },
    reuseExistingServer: false,
    timeout: 120_000,
    },
    ],
    });
  4. Créez le dossier e2e et le fichier e2e/desk.spec.ts. Ses trois tests couvrent la tâche principale au clavier, un nouveau billet avec sa tâche, et une liste défaillante qui se rétablit :

    e2e/desk.spec.ts
    // The main task, by keyboard only: find a ticket, write a draft, use it, send the reply; then a
    // new ticket and its background job. Runs on a desktop screen and on a phone screen.
    import { expect, test } from '@playwright/test';
    test.beforeEach(async ({ request }) => {
    const api = `http://127.0.0.1:${process.env.E2E_API_PORT ?? 8100}`;
    await request.post(`${api}/admin/reset`);
    });
    test('answer a ticket with the AI draft, by keyboard only', async ({ page }) => {
    await page.goto('/');
    await expect(page.getByText(/Showing \d+ tickets/)).toBeVisible();
    // Skip link, then the search box: Tab moves the focus, the keyboard types.
    await page.keyboard.press('Tab');
    await expect(page.getByRole('link', { name: 'Skip to the main content' })).toBeFocused();
    await page.getByRole('searchbox', { name: 'Search' }).focus();
    await page.keyboard.type('garden shed');
    const row = page.getByRole('link', { name: /T-80008/ });
    await expect(row).toBeVisible();
    await row.focus();
    await page.keyboard.press('Enter');
    // The focus moves to the ticket's heading.
    await expect(page.getByRole('heading', { level: 2, name: /where is my order LK-581106/i })).toBeFocused();
    // Write a draft with the keyboard; the focus stays on the same button.
    const write = page.getByRole('button', { name: 'Write a draft' });
    await write.focus();
    await page.keyboard.press('Enter');
    const status = page.locator('.draft [role="status"]');
    await expect(status).toHaveText('Draft finished. No sources.', { timeout: 15_000 });
    await expect(page.getByRole('button', { name: 'Write a new draft' })).toBeFocused();
    // The accessibility tree of the draft: what a screen reader user gets.
    await expect(page.locator('.draft')).toMatchAriaSnapshot(`
    - heading "AI draft" [level=3]
    - status: Draft finished. No sources.
    - button "Write a new draft"
    - button "Use this draft"
    - button "Discard"
    `);
    await page.getByRole('button', { name: 'Use this draft' }).focus();
    await page.keyboard.press('Enter');
    const reply = page.getByLabel('Reply to the customer');
    await expect(reply).toHaveValue(/garden shed/);
    await page.getByRole('button', { name: 'Send reply' }).focus();
    await page.keyboard.press('Enter');
    await expect(page.getByText('Sent.')).toBeVisible();
    await expect(page.locator('.message-agent').last()).toContainText('garden shed');
    });
    test('send a new ticket and follow its background job', async ({ page }) => {
    await page.goto('/#/new');
    await page.getByLabel('Customer ID').focus();
    await page.keyboard.type('C-0022');
    await page.keyboard.press('Tab');
    await page.keyboard.type('Parcel lost');
    await page.keyboard.press('Tab');
    await page.keyboard.type('My parcel did not arrive.');
    await page.keyboard.press('Tab');
    await page.keyboard.press('Enter');
    await expect(page.getByText(/Saved as T-500001/)).toBeFocused();
    await expect(page.getByText('The AI work is done.')).toBeVisible({ timeout: 20_000 });
    await expect(page.getByText(/Team: shipping/)).toBeVisible();
    });
    test('a slow, failing list says so in words and recovers', async ({ page, request }) => {
    const api = `http://127.0.0.1:${process.env.E2E_API_PORT ?? 8100}`;
    await request.post(`${api}/admin/mode`, { data: { list: 'fail' } });
    await page.goto('/');
    await expect(page.getByRole('alert')).toContainText('The ticket service is busy', { timeout: 15_000 });
    await request.post(`${api}/admin/mode`, { data: { list: 'normal' } });
    await page.getByRole('button', { name: 'Try again' }).click();
    await expect(page.getByText(/Showing \d+ tickets/)).toBeVisible();
    });

    toMatchAriaSnapshot compare l’arbre d’accessibilité du panneau de brouillon à celui dont Camille a besoin. admin/reset donne les mêmes données de départ à chaque test. admin/mode fait échouer la liste volontairement (une panne simulée).

  5. Dans package.json, remplacez tout le bloc scripts. Il ajoute test:e2e et check, et place build:profile à côté de build :

    package.json (scripts)
    "scripts": {
    "api": "node mock-api/server.mjs",
    "dev": "vite",
    "build": "tsc --noEmit && vite build",
    "build:profile": "tsc --noEmit && vite build --mode profile",
    "preview": "vite preview",
    "typecheck": "tsc --noEmit",
    "test": "node --test \"mock-api/*.test.mjs\" \"scripts/*.test.mjs\" && vitest run",
    "test:e2e": "playwright test",
    "size": "node scripts/bundle-report.mjs",
    "check:bundle": "node scripts/check-bundle.mjs",
    "check": "npm test && npm run build && npm run check:bundle && npm run size"
    }
  6. Exécutez le parcours :

    Fenêtre de terminal
    npm run test:e2e
    Running 6 tests using 1 worker
    ✓ 1 [desktop] › e2e/desk.spec.ts:10:1 › answer a ticket with the AI draft, by keyboard only (2.9s)
    ✓ 2 [desktop] › e2e/desk.spec.ts:54:1 › send a new ticket and follow its background job (5.2s)
    ✓ 3 [desktop] › e2e/desk.spec.ts:69:1 › a slow, failing list says so in words and recovers (4.5s)
    ✓ 4 [phone] › e2e/desk.spec.ts:10:1 › answer a ticket with the AI draft, by keyboard only (2.9s)
    ✓ 5 [phone] › e2e/desk.spec.ts:54:1 › send a new ticket and follow its background job (5.2s)
    ✓ 6 [phone] › e2e/desk.spec.ts:69:1 › a slow, failing list says so in words and recovers (4.5s)
    6 passed (26.9s)

    Chaque test s’est exécuté deux fois, sur l’écran d’ordinateur et sur l’écran de téléphone. Playwright a lui-même démarré et arrêté les deux serveurs.

L’écran de téléphone affichait le même panneau dans une colonne étroite. Les mêmes étapes au clavier y fonctionnaient :

Le panneau de brouillon d'IA sur un écran de taille téléphone, large de 412 pixels. La ligne d'état indique que le brouillon est terminé. Le brouillon concerne la remise de jardin. On voit la raison, la note indiquant que le brouillon n'a pas de sources, et les boutons pour rédiger un nouveau brouillon et utiliser ce brouillon sur une même ligne. Le bouton pour supprimer le brouillon est en dessous.
Le panneau de brouillon sur un écran de taille téléphone dans Chromium. Les boutons passent sur une deuxième ligne; rien n'est coupé. L’image est en anglais.

Remettez maintenant l’en-tête de Tomás dans client.ts un instant, puis exécutez seulement les tests d’ordinateur : npx playwright test --project=desktop. Les trois échouent. Le premier s’arrête là où la liste devrait apparaître :

✘ 1 [desktop] › e2e/desk.spec.ts:10:1 › answer a ticket with the AI draft, by keyboard only (5.1s)
✘ 2 [desktop] › e2e/desk.spec.ts:54:1 › send a new ticket and follow its background job (6.0s)
✘ 3 [desktop] › e2e/desk.spec.ts:69:1 › a slow, failing list says so in words and recovers (15.1s)
Error: expect(locator).toBeVisible() failed
Locator: getByText(/Showing \d+ tickets/)
Expected: visible
Timeout: 5000ms
Error: element(s) not found

Le parcours a détecté ce que 75 tests ont manqué. Retirez de nouveau l’en-tête. Si l’API a vraiment besoin d’un nouvel en-tête, Amira l’ajoute d’abord à Access-Control-Allow-Headers dans l’API.

Quand utiliser un test de bout en bout, et ce qu’il coûte. Écrivez-en un pour chaque tâche indispensable aux utilisateurs : ici, répondre à un billet et en créer un. N’en écrivez pas pour chaque état; les tests de composants les couvrent en quelques secondes. Ici, un test de bout en bout exige un téléchargement de navigateur et environ 27 secondes par exécution. Il demande aussi de l’attention : les tests doivent partir de données connues (admin/reset). Sinon, ils réussissent ou échouent au hasard.

La dernière vérification avant une livraison exécute tout ce qui ne nécessite pas de navigateur. Modifiez d’abord deux lignes dans scripts/bundle-report.mjs pour que ses nombres correspondent à ceux de Vite. Ainsi, 1 ko vaut 1 000 octets, comme l’affiche Vite, et gzip utilise le niveau par défaut de Node.

scripts/bundle-report.mjs (the size of each file)
return { file: p.slice(dir.length + 1), kb: data.length / 1000, gzipKb: gzipSync(data).length / 1000 };

Changez aussi KB en kB dans les deux lignes console.log. Ajoutez une ligne de commentaire sous la première ligne du fichier : // 1 kB = 1,000 bytes, as Vite prints. Vite compresses a little differently: its gzip numbers differ by about 1%. Puis exécutez :

Fenêtre de terminal
npm run check

La fin de la sortie, après les tests et la construction :

No secret found in 7 files of dist/.
File Size Gzip
assets/index-OCjOMpom.js 303.3 kB 92.4 kB
assets/DraftText-DPqcJ_ju.js 73.5 kB 24.6 kB
assets/LabsPage-n9IhhFGN.js 11.7 kB 3.8 kB
assets/NewTicketForm-C6gr9o0Z.js 4.2 kB 1.8 kB
assets/index-Cq7Ckq9E.css 4.2 kB 1.5 kB
assets/useJob-D5nSjGXD.js 0.9 kB 0.5 kB
index.html 0.4 kB 0.3 kB
JavaScript: 5 files, 123.1 kB gzip in all

Comparez avec Charger moins de travail : le premier écran télécharge toujours un seul fichier principal d’environ 92 ko. Le nouveau fichier DraftText (24,6 ko) arrive seulement avec un brouillon terminé.

L’équipe de Grace exploitera le bureau, et un autre développeur le modifiera. Il leur faut deux courts documents, tous deux dans docs/. Rédigez-les sous forme d’affirmations avec des preuves. Chaque phrase indique ce qui est vrai et quelle vérification ou mesure le montre.

  1. Créez docs/handoff.md : comment exécuter le bureau, les vérifications avant chaque livraison, les promesses des écrans et les limites connues :

    docs/handoff.md
    # Handoff: the ticket desk
    What the next developer needs to run, check and change the ticket desk. A worked example for the lesson *Test and deliver*.
    ## Run it
    1. `npm ci` (the exact versions of `package-lock.json`).
    2. `npm run api` in one terminal (the mock API, http://127.0.0.1:8100). In production, the real ticket API takes its place: set `VITE_API_URL` before the build.
    3. `npm run dev` in a second terminal (http://localhost:5173), or `npm run build` and `npm run preview` for the production files.
    ## Check it before every delivery
    | Check | Command | What it proves |
    |---|---|---|
    | Types | `npm run typecheck` | the code uses the API's data as the types say |
    | Component tests | `npm test` | each screen part does the right thing for a good answer, an error, a slow answer, a stop |
    | End to end | `npm run test:e2e` | one real flow by keyboard in a real browser, on a desktop and a phone screen |
    | Production build | `npm run build` | the code builds without errors |
    | No secret in the browser | `npm run check:bundle` | no server secret and no key-like text is in `dist/` |
    | Size | `npm run size` | the files that a browser downloads (compare with the last delivery) |
    `npm run check` runs the four commands that do not need a browser.
    ## What the screens promise
    - The list loads one server page (50 tickets) at a time and draws only the rows in view.
    - An old search answer never replaces a newer one (the cache key is the search).
    - A draft is shown as it is written; Stop, an interrupted connection, a failure and a finished draft look different and sound different to a screen reader. The finished draft is checked before it is trusted.
    - A status change shows at once and goes back if the server refuses it. A message to a customer is never shown as sent before the server says so.
    - The Markdown of a draft is shown without any HTML that can run code.
    ## Known limits
    - The keyboard can reach only the ticket rows that are drawn. The list box itself takes the focus and scrolls with the arrow keys; search is the fast way to a ticket.
    - After **Send reply**, the keyboard focus falls to the page: the button is disabled while the reply is sent, and nothing takes the focus back. A screen reader still hears "Sent." (a status). Fix it as the new-ticket form does: move the focus to the result.
    - The mock API has no sign-in. The authentication course adds sessions; the desk must then send its cookie with `credentials: 'include'`, and the API must allow it.
    - Tested in Chromium (desktop and a phone screen size). Not tested here: Firefox, Safari, real phones, Windows high-contrast mode.

    Les limites connues sont aussi importantes que les promesses. « Non testés ici : Firefox, Safari, vrais téléphones » indique à la prochaine équipe où regarder d’abord. La limite concernant Send reply (envoyer la réponse) vient du parcours au clavier de l’équipe du cours. C’est une vraie lacune, consignée plutôt que cachée.

  2. Créez docs/performance-note.md. Ce document consigne les mesures, l’ordinateur utilisé, ce qu’elles ont fait changer et ce qui n’a pas changé :

    docs/performance-note.md
    # Performance note: the ticket desk
    A worked example for the lesson *Test and deliver*. It says what we measured, on which computer, what we changed because of it, and what we did not change. The numbers come from the course team's measurements in Chromium (from Playwright) on one laptop (Apple M4, 16 GB). Other computers give other numbers; the differences between the rows are what matter.
    ## What we measured and what we changed
    | Question | Before | After | What we changed |
    |---|---|---|---|
    | How much JavaScript does the first screen download? (gzip) | 123.2 kB in one file | 92.4 kB, then the rest only when it is needed | code splitting: the Markdown tools of the draft, the new-ticket form and the labs load later |
    | When do the first ticket rows appear on a phone-like connection? (150 ms round trip, 1.6 Mbit/s, CPU 4 times slower) | 1,257 ms | 1,113 ms | the same code splitting (on a fast connection: 98 ms and 97 ms, no real difference) |
    | How long does it take to draw 10,000 rows? | 274 ms, 60,002 elements in the page | 30 ms, 110 elements | the list draws only the rows in view (virtualization) |
    | Does an old search answer replace a newer one? | yes: 10 of 10 tries showed the results for "p" after we typed "parcel" | no: 0 of 10 | the query key is the search, and old requests are cancelled |
    | How late does the screen show that a background job is done? | 403 ms (polling every second, 5 requests) | 29 ms (server-sent events, 1 connection) | the job lab compares both; the new-ticket form polls, because it is simpler and its delay is small |
    ## What we did not change, and why
    - **Rows in `memo`.** Typing a note above 50 rows drew the rows 1,000 times, but that cost 2.4 ms for 20 key presses. Moving the note's state down to the note removed the extra drawing without `memo`. We keep the simple version.
    - **Drawing the draft once per frame.** Drawing every piece of a recorded draft took 30 commits; once per frame took 11. Both cost less than 0.01 ms of React work per draft on this computer. We keep one commit per piece, and we do not announce every piece to screen readers.
    - **Downloading every ticket.** The list asks the server for one page of 50 tickets at a time. Downloading all 10,000 took 6.5 s and 100 requests (about 2.4 MB of JSON) before the first row could be drawn.
    ## Check it again before a delivery
    `npm run build` and `npm run size` show the files and their sizes. Compare them with this note. Measure in the browser's Performance panel with the same throttling before you change a number here.

    Le deuxième tableau est la partie honnête : trois idées semblaient bonnes, mais n’ont rien apporté, comme le montrent les nombres.

  3. Dans README.md, dans le tableau des commandes, modifiez la ligne npm test. Ajoutez trois lignes après npm run build:profile :

    README.md (the commands table)
    | `npm test` | runs the checks of the mock API, of the scripts and of the interface (Vitest and Testing Library) |
    | `npm run check:bundle` | after a build: fails if a secret is in the files that the browser downloads |
    | `npm run check` | everything before a delivery: tests, build, secret check, size report |
    | `npm run test:e2e` | one end-to-end flow by keyboard, in a real browser, on a desktop and a phone screen (first: `npx playwright install chromium`) |

    Dans le tableau des dossiers, remplacez la ligne scripts/ par ces deux lignes :

    README.md (the folders table)
    | `e2e/` | the end-to-end flow (Playwright) |
    | `scripts/`, `docs/` | the size report and the secret check; written decisions, the handoff notes and the performance note (`docs/`) |
  4. Donnez son numéro de version à la livraison. Cela modifie package.json et package-lock.json ensemble :

    Fenêtre de terminal
    npm version 1.0.0 --no-git-tag-version

    npm affiche v1.0.0.

Votre projet correspond maintenant à l’instantané end-of-m06, la version finale du projet du cours. Si quelque chose diffère, comparez vos fichiers avec cet instantané.

Erreur courante

L'exécutable n'existe pas

Symptôme : npm run test:e2e échoue immédiatement, en 16 ms :

Error: browserType.launch: Executable doesn't exist at …/chromium_headless_shell-1248/chrome-headless-shell-mac-arm64/chrome-headless-shell
╔════════════════════════════════════════════════════════════╗
║ Looks like Playwright was just installed or updated. ║
║ Please run the following command to download new browsers: ║
║ ║
║ npx playwright install ║
╚════════════════════════════════════════════════════════════╝

Cause : npm installe le code de Playwright, pas ses navigateurs. Chaque version de Playwright exige sa propre version du navigateur.

Solution : exécutez npx playwright install chromium, puis relancez les tests. Refaites-le après chaque mise à jour de @playwright/test.

Erreur courante

http://localhost:4173 est déjà utilisé

Symptôme : le parcours s’arrête avant tout test : Error: http://localhost:4173 is already used, make sure that nothing is running on the port/url or set reuseExistingServer:true in config.webServer. (l’adresse est déjà utilisée; libérez le port ou autorisez la réutilisation du serveur).

Cause : un autre programme écoute sur le port. C’est souvent un npm run preview oublié, ou l’API simulée sur 8100.

Solution : arrêtez ce programme (Ctrl+C dans son terminal). Ou choisissez d’autres ports pour le parcours : E2E_API_PORT=8200 E2E_WEB_PORT=4280 npm run test:e2e sur macOS et Linux. Dans PowerShell : $env:E2E_API_PORT=8200; $env:E2E_WEB_PORT=4280; npm run test:e2e. La configuration transmet l’adresse de l’API à la construction et autorise cette origine dans l’API simulée.

Voici l’exemple détaillé du module. Faites chaque étape et comparez votre résultat à celui présenté. C’est la même séquence que chaque livraison suit.

  1. Partez d’un état propre : supprimez dist/, puis .env s’il contient encore une valeur de test de la première leçon.
  2. Exécutez npm run check. Vous devriez voir ℹ pass 27, Tests 48 passed (48), la construction, No secret found in 7 files of dist/. (aucun secret trouvé dans les 7 fichiers de dist/) et JavaScript: 5 files, 123.1 kB gzip in all (5 fichiers JavaScript, 123,1 ko au total avec gzip).
  3. Exécutez npm run test:e2e. Vous devriez voir 6 passed (6 tests réussis) : trois parcours sur l’écran d’ordinateur et sur l’écran de téléphone.
  4. Exécutez la tâche principale à la main, uniquement au clavier, comme dans Interactions accessibles : lien d’évitement, recherche, billet, brouillon, utilisation, envoi. Le focus devrait aller sur le titre, puis sur le même bouton de brouillon. Vous devriez voir « Sent. » (envoyé) à la fin.
  5. Ouvrez docs/performance-note.md. Vérifiez que chaque nombre est accompagné de l’ordinateur utilisé et des conditions de mesure.

Votre tâche : un nouveau parcours et votre propre note

Section intitulée « Votre tâche : un nouveau parcours et votre propre note »

Les agents de Grace arrêtent souvent un brouillon qui va dans la mauvaise direction. Livrez cette tâche avec des preuves :

  1. Un parcours. Ajoutez e2e/stop.spec.ts : au clavier, ouvrez T-80008, lancez un brouillon, arrêtez-le, puis vérifiez le focus et l’état. Utilisez le flux lent simulé (admin/mode avec { stream: 'slow' }), pour avoir le temps d’appuyer sur Stop (arrêter). Le test doit réussir sur l’écran d’ordinateur et sur celui du téléphone.
  2. Une mesure. Choisissez une valeur du bureau à mesurer dans le panneau Performance de Chrome, avant et après votre propre modification. Ou mesurez de nouveau les premières lignes dans des conditions semblables à celles d’un téléphone, avec une limitation des ressources. Suivez Mesurer dans le navigateur. Ajoutez une ligne à docs/performance-note.md, avec votre ordinateur et les conditions.
  3. La livraison. Exécutez npm run check et npm run test:e2e. Ajoutez leurs dernières lignes à docs/handoff.md, sous le titre « Delivered » (livré).
Afficher une solution détaillée pour le parcours
e2e/stop.spec.ts
import { expect, test } from '@playwright/test';
const api = `http://127.0.0.1:${process.env.E2E_API_PORT ?? 8100}`;
test.beforeEach(async ({ request }) => {
await request.post(`${api}/admin/reset`);
});
test('stop a draft by keyboard, and hear that it stopped', async ({ page, request }) => {
// The slow stream (simulated: 60 ms per piece) leaves time to press Stop.
await request.post(`${api}/admin/mode`, { data: { stream: 'slow' } });
await page.goto('/#/tickets/T-80008');
await expect(page.getByRole('heading', { level: 2, name: /LK-581106/ })).toBeFocused();
await page.getByRole('button', { name: 'Write a draft' }).focus();
await page.keyboard.press('Enter');
const status = page.locator('.draft [role="status"]');
await expect(status).toHaveText('Writing the draft…');
await expect(page.getByRole('button', { name: 'Stop' })).toBeFocused();
await page.keyboard.press('Enter');
await expect(status).toHaveText('You stopped the draft. The text below is not complete.');
await expect(page.getByRole('button', { name: 'Write a new draft' })).toBeFocused();
await expect(page.getByRole('button', { name: 'Use this draft' })).toHaveCount(0);
});

L’exécution de l’équipe du cours :

✓ 4 [desktop] › e2e/stop.spec.ts:10:1 › stop a draft by keyboard, and hear that it stopped (896ms)
✓ 8 [phone] › e2e/stop.spec.ts:10:1 › stop a draft by keyboard, and hear that it stopped (880ms)
8 passed (29.6s)

La dernière vérification compte le plus : un brouillon arrêté ne doit pas proposer Use this draft (utiliser ce brouillon). Ainsi, un agent ne peut pas envoyer une demi-phrase. Pour la mesure, une bonne ligne indique la question et les conditions (« Chrome 156, Slow 4G et processeur quatre fois plus lent, cache vide »). Elle indique aussi la valeur avant et après, ainsi que la modification. Une ligne qui dit seulement « plus rapide » n’est pas une preuve.

Vérifiez votre compréhension

L'en-tête supplémentaire de Tomás a réussi les 75 vérifications de npm test, mais le bureau n'affichait aucun billet. Pourquoi les tests de composants l'ont-ils manqué, et quelle vérification l'a détecté?

Afficher la réponse

Les tests de composants remplacent fetch par une simulation qui renvoie des réponses fixes. Ils n’envoient aucune vraie requête : il n’y a donc ni origine, ni requête préliminaire, ni CORS. Le navigateur a envoyé une requête préliminaire OPTIONS à cause du nouvel en-tête. L’API simulée autorise seulement Content-Type, Idempotency-Key et X-Request-ID. Le navigateur a donc bloqué toutes les requêtes. Le parcours de bout en bout a échoué immédiatement, avec un vrai navigateur, les fichiers construits et l’API simulée en marche : getByText(/Showing \d+ tickets/) était introuvable.

Vérifiez votre compréhension

Pourquoi le bureau a-t-il 48 tests de composants, mais seulement 3 parcours de bout en bout? Utilisez les durées de l'équipe du cours.

Afficher la réponse

Sur le portable de l’équipe du cours, les 48 tests de composants ont pris environ 4,8 secondes. Les 6 tests de bout en bout (3 parcours sur 2 écrans) ont pris environ 27 secondes. Les tests de composants peuvent créer chaque état à faible coût : une erreur 404, un flux interrompu, un brouillon refusé. Ils testent donc chaque état de chaque partie. Les tests de bout en bout sont lents et nécessitent des données connues. Ils couvrent donc seulement les tâches principales et ce que seul un vrai navigateur montre : CORS, fichiers construits, flux réel et écran de téléphone.

Vérifiez votre compréhension

Vérification du module (achèvement) : quelles commandes montrent que le bureau peut être livré, et que doit afficher chacune? Comment prouvez-vous que la tâche principale fonctionne au clavier et que les fichiers regroupés ne contiennent aucun secret?

Afficher la réponse

npm run check doit se terminer par ℹ pass 27 (27 réussites), Tests 48 passed (48) (48 tests réussis) et une construction sans erreurs. Il doit aussi afficher No secret found in 7 files of dist/. (aucun secret trouvé dans les 7 fichiers de dist/.) et JavaScript: 5 files, 123.1 kB gzip in all (5 fichiers JavaScript, 123,1 ko au total avec gzip). npm run test:e2e doit afficher 6 passed (6 réussites). Son premier parcours effectue la tâche principale uniquement au clavier, sur un écran d’ordinateur et un écran de téléphone. Il vérifie le focus et l’état à chaque étape. Faites aussi cette tâche manuellement au clavier : d’abord le lien d’évitement, puis le focus sur le titre du billet. Utilisez le même bouton de brouillon et vérifiez Sent. (envoyé) à la fin. Pour les secrets, essayez aussi le test de la première leçon. Une variable VITE_ dont le nom ressemble à une clé fait échouer npm run check:bundle. La retirer fait réussir la vérification.

Récapitulatif

  • Les tests de composants, avec une API simulée, testent chaque état de chaque partie en quelques secondes. Ils ne voient ni l’API réelle, ni le navigateur, ni la construction. Un seul en-tête supplémentaire a réussi les 75 vérifications et bloqué toutes les requêtes.
  • Un parcours de bout en bout par tâche principale, dans un vrai navigateur, avec les fichiers construits, sur ordinateur et téléphone : 6 passed en environ 27 secondes. Il a détecté l’en-tête immédiatement.
  • npm run check avant chaque livraison : tests, construction, vérification des secrets, rapport de taille.
  • La remise du travail présente des affirmations avec des preuves : comment lancer et vérifier le bureau, ce que les écrans promettent, les limites connues. Elle comprend une note de performance avec l’ordinateur, les conditions et les valeurs, y compris les modifications sans gain.

Récapitulatif du module. Le bureau affiche maintenant le Markdown du modèle sans exécuter son code. Il garde tous les secrets hors du navigateur. Il fonctionne au clavier et annonce chaque changement une seule fois au lecteur d’écran. Les tests couvrent ses parties et un parcours complet. Votre projet correspond à end-of-m06.

Récapitulatif du cours. Vous avez construit le bureau de billets de Larkfield, d’une première page HTML à une application React livrée. Il charge une page de billets à la fois et n’affiche jamais une ancienne recherche. Il diffuse les brouillons d’IA en continu avec un bouton Stop et suit les tâches lentes. Il présente les sources et les erreurs en mots, et chaque gain de vitesse repose sur une mesure. Ensuite, choisissez une étude de cas : au moins une est obligatoire pour le certificat.

Leçon suivante : Recherche rapide dans un jeu de données public