👍

Couvert dans ce document

Intégration de Percy avec des tests de fonctionnalités Capybara dans n’importe quel framework web Ruby, y compris Rails, Sinatra, etc.

Si vous avez écrit des tests de fonctionnalités (ou « tests d’interface utilisateur », « tests d’acceptation », etc.), vous savez à quel point il peut être difficile de les obtenir correctement et d’obtenir votre application dans le bon état d’interface utilisateur. Percy Capybara vous permet de prendre tout le temps que vous avez passé à créer vos tests de fonctionnalités et de les développer avec des captures d’écran et des tests de régression visuelle pour couvrir tous les changements visuels de votre application, même derrière des états d’interface utilisateur complexes.

Les exemples ci-dessous supposent que vous utilisez RSpec, mais ils peuvent être facilement adaptés à d’autres frameworks de test.

🚧

Percy Capybara v4

Cette documentation est pour Percy Capybara version 4.0.0 et supérieure. Les versions antérieures de Percy Capybara avaient une API différente et incompatible.

Voir le guide de mise à niveau vers v4 ou les anciens documents.

Setup

Ajoutez cette ligne au fichier Gemme de votre application :

gem 'percy-capybara', '~> 4.0.0'

Puis exécutez:

$ bundle install

Ou installez-le vous-même avec gem install percy-capybara.

Vous devrez également installer l’agent Percy. Il s’agit d’un processus qui s’exécute parallèlement à vos tests, en téléchargeant des instantanés sur Percy en votre nom. Vous devrez utiliser npm pour l’installer.

📘

Si votre projet n’a pas déjà de fichier package.json dans le répertoire racine, exécutez npm init et suivez les instructions. package.json est comme un fichier gemme pour les paquets de nœuds.

Pour installer @percy/agentlocalement pour votre projet :

$ npm install --save-dev @percy/agent

Cela créera un répertoire ./node_modules/ contenant l’agent et ses dépendances. Le binaire exécutable de l’agent sera situé dans ./node_modules/.bin/percy.

Ensuite, importez la bibliothèque Percy Capybara dans le ou les fichiers à partir desquels vous souhaitez prendre des instantanés:

require 'percy'

Vous pouvez maintenant utiliser Percy.snapshot(...) pour générer un instantané à partir de votre test:

describe 'Test with visual testing', type: :feature, js: true do it 'loads example.com homepage' do visit 'https://example.com' Percy.snapshot(page, { name: 'example.com homepage' }) endend

L’objet page que vous passez dans Percy.snapshot est l’objet Capybara::Session qui représente la page Web testée. Il devrait être disponible dans vos tests Capybara.

Enfin, enveloppez votre commande test runner dans une commande percy exec. Cela démarrera un agent Percy local pour recevoir des instantanés de vos tests et les télécharger sur votre tableau de bord Percy.

Avant de pouvoir exécuter Percy avec succès, la variable d’environnement PERCY_TOKEN doit être définie :

# Windows$ set PERCY_TOKEN=<your token here># Unix $ export PERCY_TOKEN=<your token here>

Vous pouvez appeler percy en utilisant son chemin complet (généralement ./node_modules/.bin/percy), ou en appelant (npx est un utilitaire de nœud qui vous permet d’exécuter des binaires de paquets). Si vous utilisez une version npm antérieure à 5.2 qui ne prend pas en charge npx, vous pouvez utiliser $(npm bin)/percy à la place.

Par exemple, si vous utilisez RSpec pour exécuter vos tests, votre nouvelle commande de test devient :

$ npx percy exec -- rspec

Notez le double tiret, --, entre npx percy exec et votre commande d’exécution de test.

Vous voudrez ajouter cette commande npx percy exec -- <test runner> comme nouvelle façon pour votre système CI d’exécuter vos tests.

C’est tout! Maintenant, chaque fois que votre CI s’exécute, des instantanés de l’application dans cet état seront téléchargés sur Percy pour des tests visuels!

Configuration

Percy.snapshot(page)Percy.snapshot(page, options)

page est l’objet Capybara::Session représentant la page Web que vous souhaitez capturer. Requis.

options est un hachage facultatif qui peut inclure :

• name : Une chaîne identifiant cet instantané. Il peut s’agir de n’importe quelle chaîne qui a du sens pour vous d’identifier la page et son état. Il doit être unique et rester le même d’une génération à l’autre. Si vous ne le fournissez pas, Percy utilisera l’URL complète de la page testée. Si vous prenez plusieurs instantanés avec la même URL, vous devrez fournir manuellement des noms d’instantanés afin de désambiguer entre les deux instantanés. Pour plus de détails sur la génération de noms d’instantanés, consultez Noms d’instantanés générés automatiquement.
• widths : Un tableau d’entiers représentant les largeurs du navigateur (en pixels) auxquelles vous souhaitez prendre des instantanés.
• min_height : Un entier spécifiant la hauteur minimale de l’instantané résultant (l’instantané peut devenir supérieur à cette valeur, selon le contenu de la page). La valeur par défaut est 1024px.
• percy_css : Une chaîne contenant du CSS spécifique à Percy qui sera appliqué à cet instantané.
• request_headers : Un objet contenant des en-têtes HTTP à envoyer pour chaque requête effectuée lors de la découverte d’actifs pour cet instantané.

Exemples

Percy.snapshot(page, { name: 'Responsive snapshot', widths: })Percy.snapshot(page, { min_height: 2000 })

Configuration globale

Vous pouvez également configurer Percy pour qu’il utilise les mêmes options sur tous les instantanés. Pour voir la configuration prise en charge, y compris les largeurs, lisez notre documentation de configuration du SDK

Attente d’éléments avec Capybara

Capybara dispose d’un système d’attente interne robuste qui peut être utilisé pour attendre efficacement l’apparition de certains éléments de page avant de continuer. Vous ne devriez jamais avoir besoin d’écrire un appel sleep avec Capybara.

Avec les tests RSpec

expect(page).to have_css('#new-project')expect(page).to have_content('New Project')

Cela attendra efficacement que l’élément #new-project existe.

Sans RSpec

Vous pouvez utiliser les méthodes génériques de Capybara has_no_css?has_no_content?has_no_xpath? pour vous assurer que l’état de la page est correct avant de continuer. Vous voudrez probablement lever une exception pour arrêter l’exécution si la requête de l’élément renvoie true.

raise 'element missing!' if page.has_no_css?('#new-project')raise 'element missing!' if page.has_no_content?('New Project')

Plus d’informations

• https://github.com/teamcapybara/capybara#querying
• https://github.com/teamcapybara/capybara#asynchronous-javascript-ajax-and-friends

Dépannage

Styles manquants

Si vos captures d’écran manquent de styles et que vous utilisez Webpacker pour créer les ressources frontales de vos applications, vous devrez le configurer pour extraire le CSS lors de la création pour les tests. Par défaut, Webpack générera du CSS en tant qu’actif blob, qui ne peut pas être découvert ou enregistré lorsque nous procédons à la découverte d’actifs. Dans votre fichier de configuration de webpacker, vous devrez spécifier extract_css: true:

test: ... # Extract and emit a css file extract_css: true