Exécution en CI

Les tests qui passent sur votre machine s’exécutent en CI avec un seul changement : la clé d’API provient des secrets du système CI. Cette page couvre ce point, la façon d’utiliser les adresses pour que les exécutions parallèles ne se gênent pas, un rapport des e-mails de chaque exécution sur la pull request, et la façon de donner l’accès aux agents de codage dans le cloud.

La clé d’API comme secret

Créez une clé dans l’application sous Project settings → API keys (voir clés d’API) et enregistrez-la comme secret nommé PROXYMAIL_QA_API_KEY. Dans GitHub Actions :

.github/workflows/e2e.yml

jobs:
  e2e:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - uses: actions/setup-node@v7
        with:
          node-version: 22
      - run: npm ci
      - run: npx playwright install --with-deps
      - run: npx playwright test
        env:
          PROXYMAIL_QA_API_KEY: ${{ secrets.PROXYMAIL_QA_API_KEY }}

Les autres systèmes CI fonctionnent de la même façon : une variable CI/CD masquée dans GitLab, une variable de contexte ou de projet dans CircleCI, une variable d’environnement dans les identifiants Jenkins. Gardez la clé hors du dépôt et hors des journaux.

Une clé fonctionne dans un seul projet : donnez donc à CI son propre projet (ou au moins sa propre clé). Ses adresses restent ainsi séparées de celles que vous utilisez à la main, et la révocation de la clé CI n’affecte personne.

Une adresse par exécution, avec des plus-tags

Un compte Free dispose de 500 adresses au total, jusqu’à 50 par jour, ce qu’un pipeline chargé peut épuiser ; le plan Team n’a pas de limite. Inutile de créer une nouvelle adresse pour chaque test : un e-mail envoyé à name+anything@ arrive à name@, et l’attente sur l’adresse taguée ne trouve que les e-mails envoyés à ce tag.

Créez donc une adresse pour l’exécution, et donnez à chaque test son propre tag :

One address, a tag per test

// Once per run (Playwright's globalSetup, say): POST /v1/addresses
const base = 'k7f2x9ab12cd@mailclub.dev';

// In each test: sign up with a tagged version of it…
const address = base.replace('@', `+${process.env.GITHUB_RUN_ID}-${testInfo.workerIndex}-${Date.now()}@`);
// …then wait on that same tagged address.
// GET /v1/addresses/{address}/code only finds mail sent to that tag.

Avec le client Node.js, cela donne qa.createAddress() une fois et qa.waitForCode(tagged, { since }) par test.

Certaines applications refusent un + dans les formulaires d’inscription ; dans ce cas, créez plutôt une adresse par test. Adresses e-mail inhabituelles liste les caractères qu’un tag peut contenir.

Passez since avec l’heure à laquelle le test a envoyé le formulaire, pour qu’une attente ne récupère jamais un e-mail d’une étape ou d’une exécution précédente :

const submitted = new Date();
await page.getByRole('button', { name: 'Sign up' }).click();
// GET /v1/addresses/{address}/code?since=<submitted, ISO 8601>

Workers en parallèle

Chaque clé peut effectuer 60 requêtes par minute avec Free et 600 avec Team (limites). Une attente compte pour une requête quelle que soit sa durée (jusqu’à 30 secondes) : quelques workers en parallèle sur Free ne posent donc pas de problème. Pour les grandes suites, utilisez le plan Team ou une clé par pipeline.

Nettoyage

Supprimez les adresses à la fin de l’exécution avec DELETE /v1/addresses/{address}, par exemple dans le globalTeardown de Playwright. Tout ce que vous laissez est supprimé à expiration. Supprimer une adresse de base supprime aussi les e-mails envoyés à ses tags.

Un rapport sur la pull request

L’action Proxy Mail QA regroupe les tests d’e-mails d’un job dans une exécution et publie sur la pull request ce qu’elle a observé : quels e-mails sont arrivés et combien de temps après l’envoi du formulaire par le test, les codes, la destination de chaque lien, les vérifications d’e-mails que vous avez lancées (avec le nombre d’e-mails susceptibles d’arriver en spam, quand les vérifications anti-spam sont activées dans Labs), les vérifications de désabonnement, d’offres et de coupons, les tests en échec, et tout e-mail jamais arrivé. Le même rapport figure dans le résumé du job, et chaque membre du projet peut ouvrir l’exécution dans l’application, où QA report for this run fournit les adresses et e-mails de l’exécution sous forme de rapport QA à imprimer ou enregistrer en PDF.

.github/workflows/e2e.yml

jobs:
  e2e:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write
    steps:
      - uses: actions/checkout@v7
      - uses: aaquib90/proxymail-qa-action@v1
        with:
          api-key: ${{ secrets.PROXYMAIL_QA_API_KEY }}
      - run: npm ci
      - run: npx playwright test
        env:
          PROXYMAIL_QA_API_KEY: ${{ secrets.PROXYMAIL_QA_API_KEY }}

L’action définit PROXYMAIL_QA_RUN pour les étapes suivantes. Le client Node.js (0.5.0 ou ultérieur), le helper Python et le helper Detox et Appium la lisent : les appels que vos tests font déjà alimentent donc l’exécution. Les autres helpers mobiles la prennent de la même façon que la clé : une variable d’environnement pour XCUITest, un argument d’instrumentation pour Espresso, un --dart-define pour Flutter, et -e pour Maestro. Depuis d’autres outils, envoyez l’identifiant dans un en-tête : Proxy-Mail-QA-Run: $PROXYMAIL_QA_RUN.

Après le job, qu’il ait réussi ou non, l’action termine l’exécution et publie le rapport, en mettant à jour son commentaire à chaque push. Une exécution échoue quand un e-mail attendu par les tests n’est jamais arrivé, qu’un e-mail est arrivé alors qu’aucun n’était attendu, qu’une vérification d’e-mail a échoué, qu’un test a échoué, que des e-mails marketing sont arrivés après le désabonnement, qu’une personne a obtenu une offre deux fois, qu’un coupon a été accepté alors qu’il n’aurait pas dû l’être, ou qu’une note l’a indiqué. Pour faire aussi échouer le job dans ce cas, même si les tests ont réussi, définissez fail-job: true. Les exécutions portant le même nom partagent un commentaire : donnez donc aux jobs matriciels leur propre nom : name: e2e (${{ matrix.browser }}).

Le rapport compare aussi l’exécution avec les 10 dernières exécutions terminées du même nom, et liste ce qui a changé : les e-mails qui ont mis beaucoup plus de temps que d’habitude à arriver, un test qui reçoit maintenant deux e-mails au lieu d’un, les tests qui échouent pour la première fois ou de temps en temps, les vérifications d’e-mail qui échouent désormais, les étapes (attentes, comptages, désabonnement, vérifications d’offre et de coupon) qui ont réussi la dernière fois et ne se sont pas exécutées ou échouent maintenant, et un nouvel expéditeur ou site de lien. C’est en gardant le même nom d’une exécution à l’autre que cela fonctionne.

Les pull requests issues de forks n’ont pas accès aux secrets : dans ce cas, l’action affiche un avertissement et ne démarre aucune exécution.

@v1 suit chaque version 1.x, donc les correctifs vous parviennent sans rien changer. Pour ne prendre les changements que lorsque vous le décidez, épinglez plutôt le commit d’une version, avec son numéro en commentaire : uses: aaquib90/proxymail-qa-action@<commit> # v1.0.1. Les commits sont sur la page des tags, et Dependabot tient à jour un commit épinglé.

Une exécution conserve les adresses, les codes (avec la remise d’un coupon et la réponse du paiement), les durées, les verdicts des vérifications, les noms et erreurs des tests échoués, ainsi que le site et le chemin de chaque lien, en masquant tout ce qui ressemble à un jeton dans le chemin. Elle ne conserve jamais le texte ni l’objet d’un e-mail, ni la partie requête d’un lien, où se trouvent généralement les jetons de connexion. Les exécutions sont conservées 90 jours.

Ailleurs (un autre système de CI, ou la session d’un agent), démarrez une exécution avec POST /v1/runs, envoyez son identifiant dans l’en-tête Proxy-Mail-QA-Run, terminez-la avec POST /v1/runs/{id}/finish et récupérez le rapport avec GET /v1/runs/{id}?format=markdown. Avec le client Node.js, ce sont qa.startRun(), qa.finishRun() et qa.runReport(). Consultez la REST API.

De quel test vient chaque e-mail

Le rapport peut indiquer à quel test appartient chaque e-mail, et lister les tests échoués avec ce qu’ont fait leurs e-mails.

Playwright : importez test depuis proxymail-qa/playwright et utilisez sa fixture qa, un client qui nomme son test à chaque appel, et ajoutez le reporter, qui enregistre les tests échoués et instables ainsi que les totaux. La ligne d’un test échoué nomme l’étape ou l’action du navigateur qui a échoué (comme At “Enter the code › locator.fill(…)”) :

playwright.config.ts

export default defineConfig({
  reporter: [['list'], ['proxymail-qa/playwright/reporter']],
});

signup.spec.ts

import { test, expect } from 'proxymail-qa/playwright';

test('sign-up sends one code', async ({ page, qa }) => {
  const { address } = await qa.createAddress();
  // …sign up, wait for the code, check the email…
});

pytest : importez les hooks du helper Python dans conftest.py :

conftest.py

from proxymail_qa import pytest_runtest_setup, pytest_runtest_teardown, pytest_runtest_logreport, pytest_sessionfinish

Tests mobiles : chaque helper mobile prend le nom du test : ProxyMailQA(test:) en Swift, Kotlin et Dart, TEST dans le env d’un script Maestro, et le test Jest en cours (ou setTest) pour Detox et Appium.

Les autres outils envoient le nom du test, encodé en pourcentage, dans un en-tête Proxy-Mail-QA-Test, et les résultats à POST /v1/runs/{id}/tests (REST API). Les deux ne font rien hors d’une exécution et ne font jamais échouer les tests eux-mêmes.

Quand rien n’arrive dans CI

Quand une attente revient vide, la réponse indique pourquoi, dans la mesure où Proxy Mail QA peut le savoir (hint, et refused pour les e-mails que nous avons refusés). Dans CI, la cause habituelle est le fournisseur d’e-mail de l’environnement de staging : en mode sandbox ou test, il n’envoie qu’aux adresses vérifiées, donc l’e-mail ne part jamais. GET /v1/addresses/{address}/delivery vérifie une adresse sans attendre. Plus de détails dans L’e-mail de test n’arrive pas ?

Si toutes les exécutions échouent d’un coup, ou si l’API répond par des erreurs 5xx, consultez notre page d’état avant de modifier vos tests.

Agents de codage dans le cloud

Se connecter à l’MCP server via le navigateur nécessite une personne, donc les agents qui tournent dans le cloud utilisent une clé d’API à la place, envoyée comme jeton Bearer. Donnez-leur une clé pour un projet créé à cet effet.

Action Claude Code GitHub

Écrivez la configuration MCP dans une étape avant l’action, avec la clé issue d’un secret, et autorisez les outils dont l’agent a besoin :

.github/workflows/claude.yml

      - name: Proxy Mail QA for Claude
        run: |
          cat > /tmp/mcp.json << 'EOF'
          {
            "mcpServers": {
              "proxymail-qa": {
                "type": "http",
                "url": "https://api.proxymail.qa/mcp",
                "headers": { "Authorization": "Bearer ${{ secrets.PROXYMAIL_QA_API_KEY }}" }
              }
            }
          }
          EOF
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          claude_args: |
            --mcp-config /tmp/mcp.json
            --allowedTools mcp__proxymail-qa__get_project,mcp__proxymail-qa__create_address,mcp__proxymail-qa__wait_for_code,mcp__proxymail-qa__wait_for_link,mcp__proxymail-qa__check_delivery,mcp__proxymail-qa__delete_address

Agent de codage GitHub Copilot

Dans le Settings → Copilot → MCP servers du dépôt, ajoutez :

{
  "mcpServers": {
    "proxymail-qa": {
      "type": "http",
      "url": "https://api.proxymail.qa/mcp",
      "headers": { "Authorization": "Bearer $COPILOT_MCP_PROXYMAIL_QA_API_KEY" },
      "tools": ["get_project", "create_address", "wait_for_code", "wait_for_link", "check_delivery", "delete_address"]
    }
  }
}

Ajoutez ensuite la clé comme secret Agents nommé COPILOT_MCP_PROXYMAIL_QA_API_KEY dans l’environnement copilot du dépôt : Copilot ne transmet aux serveurs MCP que les secrets dont le nom commence par COPILOT_MCP_. L’agent de codage de Copilot ne peut pas se connecter via le navigateur, c’est pourquoi il a besoin de la clé.

Codex

Pour la CLI Codex dans un job CI (codex exec), ajoutez le serveur à ~/.codex/config.toml et définissez PROXYMAIL_QA_API_KEY à partir du secret CI :

~/.codex/config.toml

[mcp_servers.proxymail-qa]
url = "https://api.proxymail.qa/mcp"
bearer_token_env_var = "PROXYMAIL_QA_API_KEY"

La documentation de Codex ne précise pas si ses tâches cloud peuvent joindre des serveurs MCP distants. Si ce n’est pas le cas, demandez à Codex d’appeler plutôt la REST API, avec la clé issue des paramètres de l’environnement.