SixStringBny/showcase-capture

Capture de présentation

Utilisez cette compétence lorsque quelqu'un souhaite des captures d'écran, un GIF ou une visite WebM d'un projet web. L'outil exécute Playwright sur un site local ou en ligne, suit un scénario déclaratif et écrit un README ainsi qu'une galerie.

Ce qu'il produit

• screens/*.png
• README.md avec les captures d'écran et légendes
• index.html galerie
• showcase.json manifeste
• *.gif optionnel
• *.webm optionnel

Installation

Depuis le répertoire de la compétence :

node scripts/install.mjs

Depuis le paquet npm :

npx showcase-capture install

Ou manuellement :

npm install
npm run build
npx playwright install chromium

Vérifiez l'environnement :

npx showcase-capture doctor

Flux de travail

1. Inspectez le projet.

   • Framework et commande de développement.
   • Répertoire de sortie de build pour les sites statiques.
   • Routes et écrans clés.
   • Flux d'authentification et utilisateur de test.
   • Mécanisme de réinitialisation ou de préparation, généralement localStorage ou cookies.
   • Les 5 à 8 écrans qui expliquent le mieux le produit.
   • Un flux de bout en bout pour le GIF et le WebM.

2. Écrivez showcase.config.yaml.

   • Utilisez un serveur statique, de commande ou une URL en ligne.
   • Utilisez les rôles et les noms accessibles avant les sélecteurs CSS.
   • Ajoutez un bloc reset pour que chaque scène commence dans un état connu.
   • Utilisez mask pour les e-mails, jetons, noms et détails de paiement.
   • Gardez le flux GIF court : 20 à 40 secondes.

3. Validez le scénario. Cela vérifie les scènes et le flux GIF.

npx showcase-capture check

4. Capturez.

npx showcase-capture capture

5. Examinez la sortie.

   • Ouvrez README.md et index.html.
   • Vérifiez le GIF et le WebM.
   • Corrigez les sélecteurs manquants, les mauvais recadrages ou le timing.
   • Relancez avec --only <scene> lors des itérations.

6. Validez la configuration et la sortie générée.

Exemple de configuration

name: LaunchPad
baseUrl: http://localhost:5173
outDir: docs/showcase

server:
  mode: command
  command: npm run dev
  url: http://localhost:5173

reset:
  localStorage:
    - launchpad.demo.v2

context:
  locale: en-ZA
  timezoneId: Africa/Johannesburg
  fixedTime: "2026-11-09T09:00:00+02:00"
  reducedMotion: reduce

viewports:
  desktop: { width: 1440, height: 900 }
  mobile: { width: 390, height: 844 }

scenes:
  - name: desktop
    viewport: desktop
    steps:
      - goto: /
      - waitFor: h1
      - screenshot: 01-home

      - goto: /login
      - waitFor: form
      - click:
          role: button
          name: Continuer en tant qu'utilisateur test
      - waitForUrl: "#/app/dashboard"
      - screenshot: 06-dashboard

  - name: mobile
    viewport: mobile
    steps:
      - goto: /login
      - waitFor: form
      - click:
          role: button
          name: Continuer en tant qu'utilisateur test
      - waitForUrl: "#/app/dashboard"
      - screenshot: 21-mobile-dashboard

gif:
  viewport: { width: 1024, height: 640 }
  size: { width: 960, height: 600 }
  fps: 8
  steps:
    - goto: /
    - caption: [1, Découvrir, "Apprenez, associez et réservez en un seul endroit"]
    - wait: 600
    - scroll: 660
    - goto: /learn
    - caption: [1, "Explorez six modules pratiques", "Construit autour de vraies questions de freelance"]

video:
  enabled: true
  size: { width: 1280, height: 720 }

Modes de serveur

Site statique :

server:
  mode: static
  dir: dist
  spa: true

Serveur de développement :

server:
  mode: command
  command: npm run dev
  url: http://localhost:5173

URL en ligne :

server:
  mode: none
baseUrl: https://example.com

Étape de build optionnelle avant le service :

build: npm run build

Superposition

La superposition GIF est optionnelle. Utilisez-la pour correspondre à la marque du projet ou éloigner la légende du contenu important.

overlay:
  background: "rgba(8, 20, 38, 0.93)"
  accent: "#5367e8"
  font: "Inter, system-ui, sans-serif"
  offsetX: 24
  offsetY: 24

Définissez overlay.enabled: false pour enregistrer le GIF sans légendes ni curseur.

Référence des étapes

• goto: /path
• waitFor: h1 ou waitFor: { role: heading, name: Dashboard }
• click: ".selector" ou click: { role: button, name: Continuer }
• fill: { selector: "#email", value: "[email protected]" }
• press: Entrée
• hover: ".card"
• waitForUrl: "#/app/dashboard" ou waitForUrl: { pattern: "/app/", flags: "i" }
• wait: 500
• scroll: 600 ou scroll: { selector: ".footer" }
• screenshot: 01-home
• screenshot: { name: 01-home, fullPage: true }
• viewport: mobile
• caption: [1, "Titre", "Sous-titre"] (flux GIF uniquement)
• reset: true
• eval: "localStorage.setItem('key', 'value')"
• run: function (configuration TypeScript ou JavaScript uniquement)

Configuration TypeScript

Utilisez une configuration TypeScript lorsque le scénario nécessite une logique personnalisée :

import { defineShowcase } from 'showcase-capture'

export default defineShowcase({
  name: 'Mon projet',
  outDir: 'docs/showcase',
  server: { mode: 'static', dir: 'dist' },
  scenes: [
    {
      name: 'desktop',
      steps: [
        { goto: '/' },
        {
          run: async ({ page }) => {
            await page.evaluate(() => localStorage.setItem('theme', 'light'))
          },
        },
        { waitFor: 'h1' },
        { screenshot: '01-home' },
      ],
    },
  ],
})

Confidentialité

• Ne capturez pas les écrans d'administration, secrets, jetons ou détails de paiement.
• Utilisez mask pour les e-mails, noms et données de compte.
• Utilisez un compte de test avec des données fictives.
• Vérifiez le GIF et le WebM avant publication.
• L'outil ne télécharge rien.

Dépannage

• Could not launch Chromium : exécutez npx playwright install chromium ou définissez CHROME_PATH.
• Server did not respond : vérifiez la commande, le port et l'URL. Utilisez reuseExisting: true si le serveur de développement est déjà en cours d'exécution.
• waitFor expire : préférez les sélecteurs getByRole, vérifiez le titre de la page ou ajoutez un wait.
• Le GIF est trop long : raccourcissez les étapes, réduisez fps ou réduisez la zone d'affichage.
• Le WebM est manquant : vérifiez que video.enabled est true et qu'un flux gif existe.
• Les captures d'écran ont une taille incorrecte : définissez la zone d'affichage dans la scène ou la configuration.