Scarnox · Blog

Garder la CI verte quand votre application a un captcha

Votre formulaire d'inscription affiche un PopularCaptcha. Votre suite de tests bout en bout doit s'inscrire. Maintenant la CI est rouge, et la solution tentante, désactiver le captcha dans le build de test, signifie que le flux que vous testez n'est pas celui que reçoivent vos utilisateurs.

Il existe plusieurs façons de s'en sortir. Elles diffèrent par la part du flux réel qu'elles exercent, choisissez donc celle qui correspond à la question que pose votre test. Voici les options, de la moins coûteuse à la plus réaliste.

Scarnox résout PopularCaptcha aujourd'hui. Les autres types de captcha arrivent bientôt, l'option de résolution ci-dessous ne concerne donc que PopularCaptcha.

1. Clés de test pour les tests unitaires et locaux

De nombreux fournisseurs de captcha publient des clés de test qui réussissent toujours. Utilisez-les lorsque vous contrôlez l'environnement et que vous avez seulement besoin que le formulaire s'affiche et se soumette. Les clés de test n'exercent pas une vérification réelle, et elles ne servent plus dès que vous testez un environnement déployé qui utilise de vraies clés.

2. Un contournement pour votre propre staging

Certaines équipes ajoutent un en-tête secret que le backend accepte à la place d'un token de captcha. C'est rapide et gratuit, mais c'est un chemin de code qui n'existe que pour les tests, et une simple erreur de configuration suffit pour qu'il se retrouve en production. Si vous en utilisez un, protégez-le par une vérification d'environnement, rendez le secret long et aléatoire, et testez qu'il est rejeté en production.

3. Simuler l'appel de vérification

Remplacez la requête de vérification côté serveur par un bouchon (stub) dans les tests d'intégration. C'est utile pour vérifier la logique de votre backend, par exemple ce qui se passe lorsque la vérification échoue. Cela ne vous dit rien sur le fait que le front-end envoie correctement le token, associez-la donc à l'une des autres options.

4. Résoudre le captcha pour de vrai en staging et dans les tests de fumée

Lorsque vous devez prouver que le flux réel fonctionne de bout en bout, avec de vraies clés, le vrai widget et une vraie vérification, récupérez un token auprès d'une API de résolution à l'intérieur du test. C'est la seule option qui détecte une intégration de widget défaillante.

Un helper Playwright ressemble à ceci :

// Helper de test Playwright
export async function solveCaptcha(page) {
  const sitekey = await page.getAttribute("[data-sitekey]", "data-sitekey");
  const r = await fetch("https://api.scarnox.com/api/tasks/create", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.SCARNOX_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      captcha_type: "PopularCaptchaTaskProxyless",
      site_key: sitekey,
      site_url: page.url(),
    }),
  });
  const { errorId, solution, errorCode, errorDescription } = await r.json();
  if (errorId !== 0) throw new Error(`${errorCode}: ${errorDescription}`);

  await page.evaluate((t) => {
    document.querySelectorAll('[name="h-captcha-response"],[name="g-recaptcha-response"]')
      .forEach((el) => { el.value = t; });
  }, solution.token);
}

Appelez-le juste avant la soumission du formulaire dans le test, et non au début du test. Les tokens expirent en environ deux minutes, et une étape lente plus tôt dans le test peut consommer cette fenêtre.

Limitez le nombre de résolutions

Une suite qui s'inscrit à chaque exécution peut générer beaucoup de résolutions sur une semaine. Gardez le nombre bas :

Pour les règles de nouvelle tentative à l'intérieur du helper, réutilisez la politique du guide sur la gestion des erreurs et le backoff.

Gardez la clé hors du dépôt

Stockez la clé comme secret de CI, nommé par exemple SCARNOX_KEY, et ne la placez jamais dans le code de test ni dans les fixtures. Si elle fuite, régénérez-la depuis le tableau de bord. L'ancienne clé cesse immédiatement de fonctionner, une clé qui a fuité ne peut donc pas servir longtemps à lancer des résolutions.

Utilisez une clé distincte pour la CI. Si un pipeline se comporte mal, vous pouvez changer cette clé sans toucher au reste.

Essayez sur votre propre staging

Créez un compte et démarrez avec un crédit d'essai gratuit, sans carte bancaire. Branchez d'abord le helper dans un seul test de fumée, vérifiez qu'il s'inscrit proprement, puis seulement ensuite ajoutez-le au reste de la suite. Pour connaître le coût de la résolution à grande échelle, consultez les tarifs actuels.

Ce qu'il faut vérifier après la soumission

Un captcha résolu prouve seulement que l'étape du widget a fonctionné. Après la soumission, vérifiez ce qui compte pour l'utilisateur : la page suivante se charge, le message de succès apparaît, et le compte ou la commande existe dans votre base de données. Un test qui s'arrête à « aucune erreur sur le formulaire » peut réussir alors que l'inscription échoue silencieusement côté backend.

Gardez les assertions proches du résultat métier. Vérifiez l'URL, le message visible et un enregistrement créé par le test. Supprimez cet enregistrement à la fin de l'exécution pour que la suivante parte d'un état connu.

Lancer le test de fumée selon un planning

Lancez le test de fumée avec vraie résolution selon un planning, par exemple une fois par jour sur le staging, plutôt qu'à chaque pull request. Les exécutions planifiées détectent les changements que le site a faits pendant la nuit, comme une nouvelle version du widget ou une sitekey déplacée, sans dépenser de résolutions à chaque commit. Alertez l'équipe lorsque l'exécution planifiée échoue, et gardez la suite par commit sur les options plus rapides.

Étapes suivantes