👍

In diesem Dokument behandelt

Integration von Percy mit Capybara-Funktionstests in jedes Ruby-Webframework, einschließlich Rails, Sinatra usw.

Wenn Sie funktionstests (oder „UI-Tests“, „Akzeptanztests“ usw.), wissen Sie, wie schwer es sein kann, sie richtig zu machen und Ihre App in den richtigen UI-Zustand zu bringen. Mit Percy Capybara können Sie die gesamte Zeit, die Sie für die Erstellung Ihrer Funktionstests aufgewendet haben, mit Screenshots und visuellen Regressionstests erweitern, um alle visuellen Änderungen in Ihrer App abzudecken, auch hinter komplexen UI-Zuständen.

Die folgenden Beispiele gehen davon aus, dass Sie RSpec verwenden, aber sie können leicht für andere Testframeworks angepasst werden.

🚧

Percy Capybara v4

Diese Dokumentation ist für Percy Capybara Version 4.0.0 und höher. Frühere Versionen von Percy Capybara hatten eine andere und inkompatible API.

Siehe das Handbuch Upgrade auf v4 oder die alten Dokumente.

Setup

Fügen Sie diese Zeile zur Gemfile Ihrer Anwendung hinzu:

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

Und dann ausführen:

$ bundle install

Oder installieren Sie es selbst mit gem install percy-capybara.

Sie müssen auch den Percy-Agenten installieren. Dies ist ein Prozess, der neben Ihren Tests ausgeführt wird und Snapshots in Ihrem Namen an Percy hochlädt. Sie müssen npm verwenden, um es zu installieren.

📘

Wenn Ihr Projekt noch keine package.json -Datei im Stammverzeichnis hat, führen Sie npm init aus und folgen Sie den Anweisungen. package.json ist wie ein Gemfile für Node-Pakete.

So installieren Sie @percy/agent lokal für Ihr Projekt:

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

Dadurch wird ein ./node_modules/ Verzeichnis erstellt, das den Agenten und seine Abhängigkeiten enthält. Die ausführbare Binärdatei des Agenten befindet sich in ./node_modules/.bin/percy.

Importieren Sie als Nächstes die Percy Capybara-Bibliothek in die Datei(en), aus der(denen) Sie Schnappschüsse machen möchten:

require 'percy'

Jetzt können Sie Percy.snapshot(...) verwenden, um einen Schnappschuss aus Ihrem Test zu generieren:

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

Die page Objekt, das Sie an Percy.snapshot übergeben, ist das Capybara::Session Objekt, das die zu testende Webseite darstellt. Es sollte in Ihren Capybara-Tests verfügbar sein.

Schließlich wickeln Sie Ihren Test Runner Befehl in einem percy exec Befehl. Dadurch wird ein lokaler Percy-Agent gestartet, der Snapshots von Ihren Tests empfängt und sie in Ihr Percy-Dashboard hochlädt.

Bevor Sie Percy erfolgreich ausführen können, muss die PERCY_TOKEN Umgebungsvariable gesetzt sein:

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

Sie können percy mit seinem vollständigen Pfad aufrufen (normalerweise ./node_modules/.bin/percy) oder npx percy (npx ist ein Node-Dienstprogramm, mit dem Sie Paketbinärdateien ausführen können). Wenn Sie eine npm-Version vor 5.2 verwenden, die npx nicht unterstützt, können Sie stattdessen $(npm bin)/percy .

Wenn Sie beispielsweise RSpec zum Ausführen Ihrer Tests verwenden, lautet Ihr neuer Testbefehl:

$ npx percy exec -- rspec

Beachten Sie den doppelten Bindestrich -- zwischen npx percy exec und Ihrem Testlaufbefehl.

Sie sollten diesen npx percy exec -- <test runner> Befehl als neue Möglichkeit für Ihr CI-System hinzufügen, Ihre Tests auszuführen.

Das war’s! Wenn Ihr CI ausgeführt wird, werden Snapshots der App in diesem Status zum visuellen Testen auf Percy hochgeladen!

Konfiguration

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

page ist das Capybara::Session Objekt, das die Webseite darstellt, die Sie snapshoten möchten. Erforderlich.

options ist ein optionaler Hash, der Folgendes enthalten kann:

• name: Eine Zeichenfolge, die diesen Snapshot identifiziert. Es kann sich um eine beliebige Zeichenfolge handeln, die für Sie sinnvoll ist, um die Seite und ihren Status zu identifizieren. Es muss einzigartig sein und über Builds hinweg gleich bleiben. Wenn Sie es nicht angeben, verwendet Percy die vollständige URL der zu testenden Seite. Wenn Sie mehrere Snapshots mit derselben URL erstellen, müssen Sie manuell Snapshot-Namen angeben, um zwischen den beiden Snapshots zu unterscheiden. Weitere Informationen zum Generieren von Snapshot-Namen finden Sie unter Automatisch generierte Snapshot-Namen.
• widths: Ein Array von Ganzzahlen, die die Browserbreiten (in Pixel) darstellen, mit denen Sie Snapshots erstellen möchten.
• min_height: Eine Ganzzahl, die die minimale Höhe des resultierenden Snapshots angibt (der Snapshot kann je nach Inhalt der Seite höher als dieser Wert sein). Der Standardwert ist 1024px.
• percy_css: Ein String, der Percy-spezifisches CSS enthält, das auf diesen Snapshot angewendet wird.
• request_headers: Ein Objekt, das HTTP-Header enthält, die für jede Anforderung gesendet werden, die während der Asset-Erkennung für diesen Snapshot gestellt wird.

Beispiele

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

Globale Konfiguration

Sie können Percy auch so konfigurieren, dass dieselben Optionen für alle Snapshots verwendet werden. Um die unterstützte Konfiguration, einschließlich der Breiten, zu sehen, lesen Sie unsere SDK-Konfigurationsdokumente

Warten auf Elemente mit Capybara

Capybara verfügt über ein robustes internes Wartesystem, mit dem Sie effizient warten können, bis bestimmte Seitenelemente angezeigt werden, bevor Sie fortfahren. Sie sollten niemals einen flockigen sleep Aufruf mit Capybara schreiben müssen.

Mit RSpec-Tests

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

Dies wartet effizient darauf, dass das #new-project Element existiert.

Ohne RSpec

Sie können Capybaras generische has_no_css?has_no_content?has_no_xpath? Methoden verwenden, um sicherzustellen, dass der Seitenstatus korrekt ist, bevor Sie fortfahren. Sie möchten wahrscheinlich eine Ausnahme auslösen, um die Ausführung zu stoppen, wenn die Abfrage für das Element true zurückgibt.

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

Weitere Informationen

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

Fehlerbehebung

Fehlende Stile

Wenn Ihre Screenshots fehlende Stile und Sie verwenden Webpacker, um Ihre Apps-Front-End-Assets zu erstellen. Standardmäßig generiert Webpack CSS als blob Asset, das bei der Asset-Erkennung nicht erkannt oder gespeichert werden kann. In Ihrer Webpacker-Konfigurationsdatei müssen Sie extract_css: true:

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