Guide

Cypress : des tests end to end exécutés dans le navigateur

Cypress exécute les tests dans le navigateur avec l'application. Version 15, licence, configuration, sessions, Cypress Cloud, comparaison avec Playwright.

L'équipe CodeWorlds18 min de lecture ·

Pratique HTML et CSS dans des leçons interactives avec un éditeur de code.

Crée un compte gratuit→
Dans cet article9

Cypress est un outil de tests end to end dont le code de test s'exécute dans la même boucle d'événements que l'application testée. La version actuelle est la 15.21.0, sortie le 18 août 2026, le dépôt cypress-io/cypress compte environ 51 mille étoiles et le paquet npm est sous licence MIT. Ce qui coûte de l'argent, c'est le service Cypress Cloud, pas l'outil lui-même.

Ce que fait vraiment Cypress

La différence entre Cypress et le reste du marché tient en une phrase de la documentation officielle : les commandes Cypress s'exécutent dans le navigateur. Il n'y a pas de protocole réseau, pas de sérialisation d'objets en JSON, pas de processus Node qui dit à un navigateur, via une socket, de cliquer sur un élément. Le fichier de spec se charge dans le même onglet que l'application, dans une frame voisine, et a un accès direct à son objet window, au modèle de document et à tout ce que l'application expose.

Tout le reste en découle, le bon comme le mauvais. Le bon, c'est l'interface. Lancer cypress open ouvre une fenêtre avec le journal des commandes à gauche et l'application à droite. Chaque commande laisse un instantané de l'état de la page, donc survoler une entrée cy.get('[data-cy=submit]') ramène l'aperçu de l'application à l'instant précédant le clic. Cela fonctionne après la fin du test, sans rien relancer. Les concurrents reproduisent le même effet à partir d'un enregistrement et non d'un état vivant, et c'est une vraie différence au quotidien.

La deuxième conséquence est la relance automatique. Les commandes ne renvoient pas de valeur immédiatement ; elles se mettent en file et réinterrogent le modèle de document jusqu'à ce que la requête réussisse ou que defaultCommandTimeout s'écoule, valeur par défaut 4000 millisecondes. Les assertions comme .should('be.visible') sont relancées de la même façon. Les tests Cypress ne contiennent donc presque aucune attente explicite d'une condition, car le mécanisme s'en charge.

La troisième est un ensemble de limites que la documentation qualifie carrément de permanentes. Le code de test s'exécute dans le navigateur, c'est donc toujours du JavaScript et jamais autre chose. Vous ne pouvez pas piloter deux navigateurs à la fois. Chaque test est lié à un seul superdomaine. Il n'existe aucune commande qui change de contexte vers un iframe, bien que les frames de même origine puissent être interrogées avec un simple cy.get. Parler à une base de données ou à un backend passe par cy.task() et cy.request(), car on ne peut tout simplement pas importer un module Node dans une spec.

Cypress gère aussi les tests de composants, dans la même fenêtre et avec le même journal de commandes. Cela concurrence directement les tests dans Vitest avec une bibliothèque de rendu en mémoire, sauf qu'ici le composant s'affiche dans un vrai navigateur et que vous le voyez à l'écran.

Version, licence et distribution

Les versions arrivent à peu près toutes les deux semaines. Les versions 15.16.0 à 15.21.0 sont sorties entre le 26 mai et le 18 août 2026. Le champ engines exige Node ^20.1.0 || ^22.0.0 || >=24.0.0, donc Node 18 et Node 21 ne sont plus pris en charge. Le paquet compte 39 dépendances directes.

La licence se vérifie à trois endroits, car les sources ne s'accordent pas. Le fichier LICENSE du dépôt contient le texte MIT avec la mention « Copyright (c) 2023 Cypress.io ». Le champ license du registre npm pour le paquet cypress indique MIT. Le paquet publié, en revanche, une fois ses 836 entrées d'archive décompressées, ne contient aucun fichier de licence. Pas de LICENSE, pas de LICENSE.md, pas de COPYING. Si votre processus de conformité récolte les textes de licence dans node_modules, il ne récoltera rien pour Cypress et signalera la dépendance comme non documentée.

La seconde moitié de l'histoire est plus intéressante. Le paquet cypress sur npm est essentiellement un téléchargeur. Son package.json déclare "postinstall": "node dist/index.js --exec install", et ce script récupère le vrai binaire sur download.cypress.io. L'archive npm pèse moins d'un mégaoctet, alors que ce que vous exécutez réellement arrive par un canal séparé, en dehors du registre et de ses mécanismes de vérification. Le comportement peut être infléchi avec les variables CYPRESS_INSTALL_BINARY, CYPRESS_DOWNLOAD_MIRROR et CYPRESS_CACHE_FOLDER, et dans un environnement isolé du réseau il faut de toute façon le faire. La conclusion pratique est que la licence MIT décrit le code du dépôt, pas l'exécutable qui atterrit dans un cache sur votre machine de build.

Cypress Cloud est à part. C'est un service commercial fermé exploité par la même société, dont aucun code n'est public. Depuis la version 15.21.0, il existe aussi une variable CYPRESS_DISABLE_GUEST_TELEMETRY qui désactive les rapports envoyés pour les sessions sans connexion. Le simple fait qu'elle n'ait été ajoutée que maintenant indique que des événements anonymes du mode ouvert et de la ligne de commande partaient auparavant par défaut.

Installation et configuration

Entrer dans un projet se présente ainsi.

Bash
# install pinned to an exact version
npm install --save-dev --save-exact cypress

# window with the command log, setup wizard on first launch
npx cypress open

# headless run, for a continuous integration pipeline
npx cypress run

# a chosen browser and a single spec
npx cypress run --browser firefox --spec "cypress/e2e/login.cy.ts"

# component tests instead of end to end
npx cypress run --component

# a run recorded in Cypress Cloud, split across machines
npx cypress run --record --key "$CYPRESS_RECORD_KEY" --parallel \
  --ci-build-id "$GITHUB_RUN_ID" --group "e2e-chrome"

# check whether the downloaded binary starts at all
npx cypress verify

# agent access to an open session, added in 15.21.0
npx cypress tap --help

La configuration se trouve dans cypress.config.ts à la racine du projet. Voici un ensemble de champs qui existent réellement dans les définitions de types de la 15.21.0.

TypeScript
import { defineConfig } from 'cypress'

export default defineConfig({
  defaultCommandTimeout: 8000,
  pageLoadTimeout: 60000,
  requestTimeout: 5000,
  responseTimeout: 30000,
  viewportWidth: 1280,
  viewportHeight: 800,
  video: false,
  videoCompression: false,
  screenshotOnRunFailure: true,
  trashAssetsBeforeRuns: true,
  numTestsKeptInMemory: 20,
  experimentalMemoryManagement: true,
  retries: { runMode: 2, openMode: 0 },
  blockHosts: ['*.google-analytics.com', '*.hotjar.com'],
  e2e: {
    baseUrl: 'http://localhost:3000',
    specPattern: 'cypress/e2e/**/*.cy.{ts,tsx}',
    supportFile: 'cypress/support/e2e.ts',
    testIsolation: true,
    setupNodeEvents(on, config) {
      on('task', {
        resetDatabase: async () => {
          await fetch(`${config.env.apiUrl}/test/reset`, { method: 'POST' })
          return null
        }
      })
      return config
    }
  },
  component: {
    devServer: { framework: 'react', bundler: 'vite' },
    specPattern: 'src/**/*.cy.{ts,tsx}'
  }
})

Quelques champs méritent un commentaire. retries accepte des valeurs distinctes pour le mode run et le mode open, et définir des retries en mode open n'a généralement pas de sens, car cela masque l'échec que vous essayez justement d'examiner. numTestsKeptInMemory vaut 50 par défaut et c'est l'une des principales raisons pour lesquelles le navigateur gonfle pendant de longues specs ; l'abaisser vous coûte les instantanés des tests plus anciens. experimentalMemoryManagement est parfois nécessaire dans des conteneurs avec une limite de mémoire stricte. La valeur par défaut de videoCompression est false, même si les définitions de types affirmaient à tort jusqu'à récemment 32.

La boucle de débogage, le point fort de l'outil

Le test lui-même a l'air ordinaire, mais ce qui compte, c'est ce qui se passe après son exécution.

TypeScript
describe('cart', () => {
  beforeEach(() => {
    cy.task('resetDatabase')
    cy.visit('/shop')
  })

  it('adds a product and recalculates the total', () => {
    cy.intercept('POST', '/api/cart', { statusCode: 201, body: { items: 1 } }).as('addToCart')

    cy.get('[data-cy=product-card]').first().within(() => {
      cy.get('[data-cy=add-to-cart]').click()
    })

    cy.wait('@addToCart').its('request.body').should('deep.equal', { sku: 'CW-001', qty: 1 })

    cy.get('[data-cy=cart-total]')
      .should('be.visible')
      .and('contain.text', '129.00')

    cy.window().its('localStorage.cartId').should('be.a', 'string')
  })
})

Une fois ce test terminé, la fenêtre Cypress affiche une liste de quatre étapes. Cliquez sur cy.wait('@addToCart') et la console du navigateur affiche les objets complets de la requête et de la réponse. Survolez .click() et l'aperçu revient à l'état précédant le clic. Épinglez l'étape, passez aux outils de développement et fouillez le modèle de document à cet instant précis. Rien de tout cela ne demande une nouvelle exécution.

La commande cy.window() montre au passage ce qu'apporte l'exécution du code de test dans le navigateur. Vous atteignez le véritable objet window de l'application, pas une représentation envoyée par un protocole. Vous pouvez y lire l'état d'un store Redux, remplacer une méthode d'un objet global ou appeler une fonction exposée par l'application. Dans les outils qui pilotent un navigateur de l'extérieur, la même chose exige de passer une fonction à évaluer de l'autre côté et de ne recevoir en retour que des valeurs sérialisables.

La version 15.21.0 a ajouté la commande cypress tap, qui expose une session ouverte à un agent. Ses sous-commandes listent les sessions en cours, lancent et relancent une spec, rapportent l'état et les résultats d'une exécution, affichent l'erreur d'un test en échec avec son journal de commandes, et montrent le modèle de document et l'arbre d'accessibilité de l'application testée. Chacune affiche par défaut du texte lisible et, avec --json, des données exploitables par une machine. Pour qui écrit des tests avec GitHub Copilot ou un autre assistant, c'est un changement concret, car l'agent cesse de deviner pourquoi un test a échoué.

Sessions, réseau et origines multiples

Trois commandes décident si une suite sera rapide ou non.

TypeScript
// log in once per spec rather than before every test
const login = (email: string, password: string) => {
  cy.session([email, password], () => {
    cy.visit('/login')
    cy.get('[data-cy=email]').type(email)
    cy.get('[data-cy=password]').type(password, { log: false })
    cy.get('[data-cy=submit]').click()
    cy.url().should('include', '/dashboard')
  }, {
    cacheAcrossSpecs: true,
    validate: () => {
      cy.request('/api/me').its('status').should('eq', 200)
    }
  })
}

// logging in through an external identity provider
it('logs in through an external provider', () => {
  cy.visit('/login')
  cy.get('[data-cy=sso]').click()

  cy.origin('https://accounts.example.com', { args: { user: 'alice@example.com' } }, ({ user }) => {
    cy.get('input[name=identifier]').type(user)
    cy.get('button[type=submit]').click()
  })

  cy.url().should('include', '/dashboard')
})

cy.session() stocke les cookies ainsi que le contenu de localStorage et sessionStorage, et à l'appel suivant avec le même identifiant il les restaure au lieu de repasser par le formulaire. L'option cacheAcrossSpecs vaut false par défaut, donc sans elle le cache de session se termine avec la spec. La fonction validate vérifie si la session restaurée est toujours valide, et en cas d'échec Cypress la reconstruit. Sans ce mécanisme, chaque test se connecte par le formulaire et la suite devient plusieurs fois plus lente.

cy.origin() est le moyen de contourner la restriction d'un seul superdomaine. Le bloc passé à cette commande s'exécute dans le contexte d'une autre origine, mais c'est un monde séparé : il ne voit aucune variable de la portée environnante, donc tout doit passer par args, et les valeurs doivent être sérialisables. Importer un module dans le bloc exige d'activer experimentalOriginDependencies. Pour un seul flux de connexion, cela suffit. Pour un test qui saute entre trois origines et compare leur état, le code devient lourd.

cy.intercept() capte les requêtes réseau et permet de les remplacer ou simplement de les observer. Cypress fait transiter les connexions WebSocket de façon transparente et peut voir la requête de changement de protocole comme resourceType: 'websocket', mais simuler des trames individuelles n'est pas pris en charge. Si vous testez un chat ou des notifications en direct, c'est la limite de l'outil.

Cypress Cloud, ou ce que vous payez

L'outil lui-même est gratuit et sans restriction. Ce que vous payez, c'est le service qui reçoit les résultats d'exécution, et il gouverne deux choses qui comptent dans un pipeline : la parallélisation et la relecture des exécutions. Les options --parallel et --record exigent une clé de projet, car c'est le serveur Cypress Cloud qui répartit les specs entre les machines et équilibre la charge à partir des durées historiques.

Contrairement à une idée répandue, la parallélisation et Test Replay sont aussi disponibles sur le plan gratuit. La limite n'est pas la fonction mais le compteur. Le plan Starter couvre 50 utilisateurs, 500 résultats de test par mois, 100 exécutions de prompts de génération de tests par mois, 30 jours de rétention des données et le seul support communautaire. Un résultat de test est un test dans une exécution, donc une suite de 60 tests déclenchée à chaque merge consomme ce quota en moins de neuf exécutions. Pour un projet en solo, c'est suffisant ; pour une équipe, non.

Les tarifs des plans supérieurs se lisent ainsi sur la page des prix. Le plan Team coûte 799 dollars par an et couvre 120 mille résultats de test par an, 9 mille exécutions de prompts, 90 jours de rétention, plus la détection des tests instables et une intégration Jira. Le plan Business coûte 3199 dollars par an, avec les mêmes 120 mille résultats, 24 mille exécutions de prompts, la priorisation des specs, l'annulation automatique des exécutions et l'authentification unique. Enterprise est négocié, avec des utilisateurs illimités, 1,8 million de résultats par an et 180 jours de rétention.

Deux points de cette grille appellent une précision. Les cartes de plans affichent des montants mensuels de 67 et 267 dollars, mais ce sont les prix annuels divisés par douze et arrondis au supérieur, puisque 799 divisé par douze donne 66,58 et 3199 divisé par douze donne 266,58. Multiplier le montant mensuel par douze ne correspond pas au montant annuel, et ce n'est pas une offre distincte. Le second point est le coût du dépassement : les résultats achetés à l'avance reviennent à 5,28 dollars les mille sur Team, 4,40 sur Business et 4,00 sur Enterprise, tandis que les résultats facturés après coup reviennent respectivement à 6 et 5 dollars les mille. C'est là que la facture grossit sans bruit, car chaque nouvelle tentative d'un test en échec compte.

L'alternative est de paralléliser à la main : répartir les specs entre les machines avec une matrice de jobs dans votre système d'intégration continue et passer la plage avec --spec. Vous perdez l'équilibrage de charge fondé sur l'historique, et le rapport doit être assemblé à partir de fichiers séparés. Pour une centaine de specs sur quatre machines, cela fonctionne et ne coûte rien.

Cypress face aux alternatives

FonctionCypressPlaywrightSelenium WebDriverWebdriverIOPuppeteer
Où s'exécute le code de testdans le navigateurdans Nodedans Nodedans Nodedans Node
Langages de testJavaScript et TypeScriptJS, TS, Python, Java, .NETde nombreux langagesJavaScript et TypeScriptJavaScript et TypeScript
Plusieurs onglets dans un testvia le plugin @cypress/puppeteeren natifen natifen natifen natif
Plusieurs originesvia cy.originen natifen natifen natifen natif
Parallélisationexige Cypress Cloudintégrée, option workersvia Selenium Gridintégrée, option maxInstancesvotre propre implémentation
Moteurs de navigateurChromium et Firefox, WebKit expérimentalChromium, Firefox, WebKitselon le driverselon le driverChromium et Firefox
Version actuelle15.21.01.62.14.47.09.31.225.8.0
Licence du paquet npmMITApache 2.0Apache 2.0MITApache 2.0

Le choix tient à quelques questions. Si le parcours testé touche plusieurs onglets, plusieurs origines ou plusieurs utilisateurs simultanés, un chat par exemple, ou un document modifié par deux personnes, Playwright l'emporte sans discussion et il n'y a rien à enjoliver. Si l'équipe doit écrire des tests en Python ou en Java, Cypress n'est pas du tout candidat. Si la parallélisation dans le pipeline doit être intégrée et gratuite, Playwright est encore le choix le plus simple.

Cypress l'emporte encore là où comptent le temps d'intégration et le temps pour trouver la cause d'un échec. Des instantanés d'état après chaque commande, une fenêtre unique au lieu d'un rapport dans un navigateur, pas besoin de comprendre l'asynchronisme de JavaScript pour écrire ses premiers tests. Pour une équipe où les tests sont aussi écrits par quelqu'un en dehors du groupe de développement principal, cette différence se sent. S'y ajoutent les tests de composants dans un vrai navigateur, qui s'associent sensiblement à React et à un catalogue de composants dans Storybook, là où le rendu en mémoire ne suffit pas.

Erreurs courantes

La première est d'utiliser cy.wait() avec un nombre de millisecondes. Comme les commandes se relancent de toute façon jusqu'à réussir, une attente fixe ne fait qu'allonger l'exécution et ne garantit toujours pas que la condition était remplie. La forme correcte est cy.wait('@alias') après avoir intercepté une requête, ou une assertion qui se relance toute seule.

La deuxième est de traiter le résultat d'une commande comme une valeur ordinaire. const el = cy.get('.item') ne renvoie pas un élément, il renvoie un objet de file. Vous obtenez la valeur dans .then() ou via cy.wrap(). Mélanger async et await avec la chaîne de commandes aboutit à un test qui passe pour de mauvaises raisons.

La troisième est d'utiliser des sélecteurs fondés sur des classes CSS ou sur le texte des boutons. Une classe change au prochain remaniement du style, et le texte change avec une traduction. L'attribut data-cy est laid dans le balisage et peu coûteux à maintenir, et c'est le bon compromis.

La quatrième est de se connecter par le formulaire avant chaque test. Utilisez plutôt cy.session() avec cacheAcrossSpecs: true et une fonction validate. Sans cacheAcrossSpecs, le cache se termine avec le fichier de spec, ce qui sur une centaine de fichiers veut dire une centaine de connexions.

La cinquième est de désactiver testIsolation pour que les tests dépendent les uns des autres en séquence. Le champ existe et vaut true par défaut, mais le passer à false produit une suite où l'échec du troisième test fait tomber tous les suivants, avec une cause impossible à lire dans le rapport.

La sixième est de prendre les retries pour un remède à l'instabilité. retries: { runMode: 2 } masque le problème et double la facture Cypress Cloud, car chaque répétition compte comme un résultat de test distinct. Les retries ont du sens comme filet de sécurité, pas comme moyen de garder le pipeline au vert.

La septième est de ne pas mettre le binaire en cache dans le pipeline. Le paquet npm télécharge l'exécutable à chaque installation, donc sans conserver le répertoire désigné par CYPRESS_CACHE_FOLDER, chaque exécution commence par récupérer plusieurs centaines de mégaoctets sur le serveur de l'éditeur.

La huitième est d'omettre l'entrée des types dans la configuration. Les définitions de types sont livrées dans le paquet, mais sans "types": ["cypress"] dans tsconfig.json l'éditeur ne connaît ni cy ni Cypress, ce qui, dans un projet TypeScript, supprime la moitié de l'intérêt de la complétion.

FAQ

Cypress est-il gratuit ?

L'outil lui-même l'est, sous MIT, sans restriction d'usage commercial et sans plafond d'exécutions locales ou en pipeline. Ce qui coûte de l'argent, c'est le service Cypress Cloud, même si le plan Starter est gratuit et couvre 500 résultats de test par mois plus 30 jours de rétention des données. Les plans supérieurs coûtent 799 et 3199 dollars par an.

La parallélisation exige-t-elle un plan payant ?

Elle n'exige pas de plan payant, mais elle exige un compte Cypress Cloud, car c'est le serveur du service qui répartit les specs entre les machines. Sur le plan gratuit, elle tient dans le quota de 500 résultats par mois. L'alternative sans le service est de répartir vous-même les specs avec --spec et une matrice de jobs dans votre système d'intégration continue, au prix de la perte de l'équilibrage de charge.

Cypress gère-t-il plusieurs onglets et plusieurs origines ?

Plusieurs onglets, pas en natif ; la documentation renvoie au plugin @cypress/puppeteer en version 0.1.8. Les origines multiples fonctionnent via cy.origin(), où le bloc s'exécute dans un contexte séparé, les arguments passent par args et doivent être sérialisables. Cela couvre la connexion via un fournisseur externe, mais pas les scénarios inter-origines élaborés.

Quand choisir Playwright plutôt que Cypress ?

Quand vous avez besoin de plusieurs onglets, de plusieurs utilisateurs simultanés, de tests en Python ou en Java, d'une parallélisation intégrée sans service externe, ou d'une prise en charge complète du moteur WebKit, qui reste marquée comme expérimentale dans Cypress. Pour des parcours simples à origine unique, la différence est faible et c'est le confort de débogage qui tranche.

Le paquet npm contient-il un fichier de licence ?

Non. Le dépôt a un fichier LICENSE avec le texte MIT et le registre npm indique MIT, mais l'archive publiée de la 15.21.0 ne contient aucun fichier de licence. De plus, le binaire réel n'est pas du tout publié sur npm ; il est récupéré sur le site de l'éditeur par le script postinstall.

Cypress remplace-t-il les tests unitaires ?

Non, et le détourner dans ce sens ne vaut pas la peine. Les tests de composants Cypress affichent un composant dans un vrai navigateur, ce qui a du sens pour vérifier les styles, les événements de saisie et l'accessibilité. Pour des tests de logique rapides sans modèle de document, un runner qui s'exécute dans Node est un ordre de grandeur plus rapide.

La documentation se trouve sur le site de documentation de Cypress, la liste des limites permanentes dans la section des compromis, et le code source dans le dépôt GitHub.

À lire aussi