Scrutineer — front (console Web Component)

Scrutineer est une librairie bicéphale (back + front, pilotée par contrat) qui ajoute à votre application une console de recette manuelle : préconditions pré-seedées, scénarios joués depuis vos vrais écrans, résultats horodatés et historisés.

Ce dépôt est le front : <scrutineer-console>, un Web Component (Shadow DOM) sans build ni dépendance, qui embarque toute sa présentation (panneau déplaçable/redimensionnable) et ne parle que le contrat OpenAPI. Il fonctionne donc contre n'importe quel back conforme — l'implémentation de référence est le bundle Symfony : 👉 scrutineer-symfony.

Le contrat (source de vérité)

Ce dépôt héberge le contrat — la surface d'intégration langage-neutre entre le front et n'importe quel back :

• contract/openapi.yaml — la surface HTTP (catalog · availability · reset · events · history · publish, + poste · mails pour la capture des mails) ;
• contract/scenario.schema.json — le descripteur de scénario.

Le contrat vit ici, côté front, et non dans un back : le front est le consommateur invariant (il ne parle que l'OpenAPI), tandis que les backs sont remplaçables (PHP aujourd'hui, un back Python demain). Chaque back se conforme à ce contrat — voir scrutineer-symfony, l'implémentation de référence.

Installation (front)

Le composant est isolé (Shadow DOM) : il s'embarque dans React / Vue / Next / vanilla indifféremment. Deux façons de le charger.

Option A — servi par le back (recommandé)

Le back Symfony sert déjà l'asset à GET <prefix>/console.js (+ les add-ons de langue console.<lang>.js) : rien à installer côté front, on pointe simplement le <script> dessus.

<script src="/scrutineer/console.js"></script>
<script src="/scrutineer/console.fr.js"></script> <!-- optionnel : une locale -->

Option B — en dépendance npm

npm i @codeheures/scrutineer-console

import '@codeheures/scrutineer-console'; // enregistre l'élément <scrutineer-console>

Ajouter la console à votre page

Charger le script (option A) ou l'importer (option B) ne fait qu'enregistrer l'élément <scrutineer-console> — ça ne l'affiche pas. Il reste à poser l'élément dans vos pages, là où vous voulez le panneau (typiquement sur vos vrais écrans) :

<scrutineer-console active></scrutineer-console>

Le panneau ne rend que si l'attribut active est présent — c'est l'hôte qui décide de l'afficher. Dans un framework, posez le même élément dans votre template / JSX (voir Intégration dans un framework plus bas).

Attributs de <scrutineer-console>

| Attribut | Rôle | |---|---| | base | Préfixe HTTP de l'API (défaut /scrutineer, relatif = même origine). Seul endroit où l'adresse de l'API est déclarée. | | lang | Locale 2 lettres (défaut en, fallback anglais). Charger console.<lang>.js en plus. | | active | Présent = mode recette on (le panneau rend et charge le catalogue) ; absent = rien ne rend. L'activation est une décision de l'hôte. | | auth-token | (optionnel) bearer ajouté en Authorization (les sessions cookie passent aussi). |

Cross-origin (API sur un autre host)

Donnez à base l'URL absolue de l'API et servez console.js depuis cette même API. Côté hôte, câbler : CORS de l'API (origine du front avec credentials — le composant fetch en credentials: 'include') et CSP du front (origine de l'API dans script-src et connect-src).

<script src="https://api.exemple.test/scrutineer/console.js"></script>
<scrutineer-console base="https://api.exemple.test/scrutineer" lang="fr" active></scrutineer-console>

Onglet « Boîte mail » (capture des mails)

Si le back active la capture des mails de recette (voir scrutineer-symfony), la console gagne automatiquement un onglet « Boîte mail » : tous les mails d'un domaine donné (ex. [email protected]) sont interceptés et affichés ici au lieu d'être envoyés dans une vraie boîte mail.

Intégration dans un framework (React / Next)

Chargez le(s) <script> (par ex. dans un effet de montage), puis rendez l'élément <scrutineer-console> en reflétant le flag d'activation (par navigateur) sur l'attribut active :

'use client'; // Next.js : le web component vit côté navigateur

import { useEffect } from 'react';

export function StagingConsole({ active }) {
  // Charge l'asset servi par le back, une seule fois.
  useEffect(() => {
    if (document.getElementById('scrutineer-js')) return;
    const s = document.createElement('script');
    s.id = 'scrutineer-js';
    s.src = '/scrutineer/console.js'; // + '/scrutineer/console.fr.js' pour une locale
    document.body.append(s);
  }, []);

  // `active` présent ⇒ le panneau s'affiche ; absent ⇒ rien ne rend (décision hôte).
  return <scrutineer-console base="/scrutineer" lang="fr" active={active ? '' : undefined} />;
}

Le back (dépôt compagnon)

Le front a besoin d'un back conforme au contrat pour servir le catalogue, l'historique et le reset. Voir scrutineer-symfony pour l'installation du bundle et l'implémentation des ports.

Licence

MIT.