21. Jun 2021
Lesedauer 9 Min.
Mit Googles Werkzeugkiste
Web-UI- und End-to-End-Tests
Mit Puppeteer Sharp, .NET, JavaScript und einem Chromium-Browser Webseiten testen.
dotnetpro
In Mike Cohns Testpyramide (Bild 1) stehen UI-Tests ganz oben und machen nur einen kleinen Anteil an den gesamten Tests aus [1]. Bei Entwicklern stehen diese Tests in der Beliebtheit oft an letzter Stelle. UI-Tests (hier als End-to-End-Tests verstanden und synonym dazu verwendet) sind aufwendig in der Entwicklung, zeitintensiv im Ablauf und werden relativ oft geändert. Da ist es verlockend, diese Tests manuell auszuführen, was am Ende aber leicht dazu führt, dass sie nur ab und zu eingesetzt und Seiteneffektfehler übersehen werden.
Die Testpyramidenach Mike Cohn(Bild 1)
Autor
Für Webseiten-Projekte bestehen manuelle Tests darin, einzelne Webseiten aufzurufen und typische Nutzeraktionen auszuführen, wie zum Beispiel den Kauf eines Produkts oder die Anmeldung für einen Newsletter. Gesucht ist also eine Lösung, die diese manuellen Aufgaben automatisiert und am besten so ausführt, wie der Anwender es machen würde, sodass auch CSS-Probleme auffallen, wenn beispielsweise eine Schaltfläche nicht sichtbar ist.„Für solche Tests gibt es doch Selenium, das ist Open Source, kostenlos und unterstützt alle gängigen Browser“, werden erfahrene Testexperten jetzt sagen. Das stimmt und es gibt auch eine Vielzahl weiterer Tools, die Ähnliches von sich behaupten können. Die browserübergreifende Unterstützung dieser Tools führt aber zu einer weiteren Abstraktionsschicht. Um es einfach zu halten und weil es für Puppeteer Sharp noch weitere spannende Anwendungsfälle gibt (mehr dazu am Ende), ist Puppeteer Sharp jedoch einen näheren Blick wert [2].
zeit Google Chrome, Microsofts Edge und Opera mit zusammen etwa 65 Prozent Marktanteil in Deutschland [3]. Puppeteer selbst unterstützt zusätzlich noch Firefox (21 Prozent Marktanteil), Puppeteer Sharp ist in dieser Hinsicht noch nicht so weit.
Einfacher Einstieg für .NET-Entwickler
Für den einfachen Einstieg in das Thema automatisierter Web-UI-Tests hat der Autor Puppeteer Sharp schätzen gelernt. Dabei handelt es sich um die C#-Portierung von Googles Node.js-Projekt Puppeteer (dt. Puppenspieler). Mit dieser Bibliothek lassen sich Chromium-basierte Browser automatisiert steuern. Besonders hilfreich ist dabei der sogenannte Headless-Modus, bei dem das Browserfenster nicht angezeigt wird. Dadurch kann der UI-Test auch auf einem Server erfolgen.Die Entwicklung erfolgt dank Puppeteer Sharp überwiegend in C# und in etwas JavaScript. Als Browser kommt jeder auf Chromium basierende Browser infrage, die namhaftesten sind der-zeit Google Chrome, Microsofts Edge und Opera mit zusammen etwa 65 Prozent Marktanteil in Deutschland [3]. Puppeteer selbst unterstützt zusätzlich noch Firefox (21 Prozent Marktanteil), Puppeteer Sharp ist in dieser Hinsicht noch nicht so weit.
Selektor kurz erklärt
Der Selektor document.querySelectorAll(<em>'#messages li'</em>) funktioniert wie folgt:
Hello World
In Listing 1 ist das denkbar einfachste Programm für Puppeteer Sharp umgesetzt. Dazu ist eine neue Konsolenanwendung zu erzeugen, das NuGet-Paket Puppeteer Sharp zum Projekt hinzuzufügen und die Main()-Methode durch diejenige aus dem Listing zu ersetzen. Dabei muss gegebenenfalls der Wert von ExecutablePath noch auf das eigene System angepasst werden.Listing 1: Puppeteer Sharps Version von „Hello World“
<span class="hljs-function"><span class="hljs-keyword">static</span> <span class="hljs-keyword">async</span> Task <span class="hljs-title">Main</span>(<span class="hljs-params"><span class="hljs-keyword">string</span>[] args</span>) </span><br/>{ <br/> <span class="hljs-keyword">var</span> browser = <span class="hljs-keyword">await</span> Puppeteer.LaunchAsync(<br/> <span class="hljs-keyword">new</span> LaunchOptions <br/> { <br/> Headless = <span class="hljs-literal">true</span>, <br/> ExecutablePath = <span class="hljs-string">@"C:\Program Files (x86)\</span><br/><span class="hljs-string"> Microsoft\Edge\Application\msedge.exe"</span> <br/> }); <br/> <span class="hljs-keyword">var</span> page = <span class="hljs-keyword">await</span> browser.NewPageAsync(); <br/> <span class="hljs-keyword">await</span> page.GoToAsync(<br/> <span class="hljs-string">"https://www.dotnetpro.de"</span>); <br/> <span class="hljs-keyword">await</span> page.ScreenshotAsync(<br/> <span class="hljs-string">@"c:\temp\dotnetpro.jpg"</span>); <br/>}
Das Programm startet Edge, öffnet eine neue Registerkarte und lädt darin die Homepage der dotnetpro. Anschließend erstellt es davon einen Screenshot. Wird der Parameter Headless = false gesetzt, erscheint das Browserfenster, versehen mit dem Warnhinweis „Microsoft Edge wird durch automatisierte Testsoftware gesteuert“ (Bild 2).
Edge zeigtüber dem Inhalt einen Hinweistext, dass die Registerkarte automatischgesteuert wird(Bild 2)
Autor
Die Möglichkeit, Puppeteer Sharp bei der Arbeit zuzusehen, ist beim Entwickeln von End-to-End-Tests hilfreich, wenn etwas nicht wie gewünscht funktioniert. (Außerdem gibt es kaum ein schöneres Gefühl als die Gewissheit, künftig weniger monotone manuelle Tests ausführen zu müssen.)
Technischer Hintergrund
Bevor es an den ersten UI-Test geht, ist es sinnvoll, das Puppeteer-Objektmodell zu verstehen [4], das auch für Puppeteer Sharp gilt (Bild 3). Puppeteer kommuniziert über das Chrome-DevTools-Protokoll [5] mit dem Browser. Dabei sind folgende Ebenen von Interesse:
Das vereinfachtePuppeteer-Objektmodell(Bild 3)
Autor
- BrowserContext: Definiert eine Browser-Session, in der Daten geteilt werden. Ein Browserfenster im privaten Modus besitzt einen eigenen Kontext im gleichen Browserprozess.
- Page: Eine Registerkarte im Browser. Jedes Page-Objekt hat mindestens einen Frame, den MainFrame. Durch iframe- oder frame-Tags können weitere Frames erzeugt werden.
- Frame: Jeder Frame hat mindestens den Standard-Ausführungskontext (execution context). In ihm wird das JavaScript des Frames ausgeführt. Weitere Ausführungskontexte kann es für Browser-Extensions geben.
Das getestete Projekt
Als zu testendes System wird Microsofts IntegrationTestSample-Projekt für Razor Pages verwendet [6]. Es arbeitet mit einer In-Memory-Datenbank und stellt ein rudimentäres Message Board zur Verfügung (Bild 4). Dort werden Nachrichten angezeigt, es können Nachrichten ergänzt oder gelöscht werden und der Server kann die durchschnittliche Wortlänge aller Nachrichten berechnen. In der Praxis sollte keine In-Memory-Datenbank, sondern eine eigene Testdatenbank verwendet werden, die dem Live-System möglichst gleicht.
Microsofts Razor Pagesfür das Beispielprojekt zu den Integrationstests dient als zu testendes System(Bild 4)
Autor
Ein erster Webtest
Mit diesem Wissen ausgestattet, lässt sich mithilfe von NUnit [7] ein erster einfacher Webtest entwickeln. Dieser folgt dem Arrange-Act-Assert(AAA)-Muster [8] und soll lediglich die Startseite aufrufen und die Anzahl der vorhandenen Nachrichten (drei) zählen. Das Beispiel beginnt mit dem Start des Webservers, dazu gibt es die Hilfsklasse aus Listing 2. In der Praxis könnten hier auch die Datenbank zurückgesetzt oder mehrere parallele Instanzen des Servers gestartet werden; da es hier um Puppeteer Sharp geht, genügt die einfache Variante, in welcher der Server aus dem bin\Debug-Folder aufgerufen wird.Listing 2: Die Hilfsklasse zum Webserver-Start
public class SimpleServerStarter <br/>{ <br/> private Process process; <br/><br/> public void StartServer() <br/> { <br/> RootUri = "https://localhost:5001";<br/> //könnte auch ausgelesen werden <br/> process = new Process() <br/> { <br/> StartInfo = new ProcessStartInfo <br/> { <br/> FileName = @"..\..\..\..\" +<br/> "RazorPagesProject\bin\Debug\" +<br/> "netcoreapp3.1\" +<br/> "RazorPagesProject.exe", <br/> UseShellExecute = true, <br/> CreateNoWindow = false<br/> //zeigt das Server-Log, wenn false <br/> } <br/> }; <br/> process.Start(); <br/> Task.Delay(2000).Wait();<br/> //Serverstart abwarten <br/> } <br/><br/> public string RootUri { get; set; } <br/> public void StopServer() =&gt;<br/> process.CloseMainWindow(); <br/>}
Die Testklasse ist in Listing 3 zu sehen. Im Konstruktor werden Webserver und Chromium-Browser gestartet, die nach Ausführung aller Tests mit Disposed() „abgeräumt“ werden. Der Ausdruck IgnoreHTTPSErrors = true ist nötig, da im Beispiel nur ein selbst erzeugtes Zertifikat verwendet wird und es sonst zu Fehlermeldungen im Browser kommt.
Listing 3: Der erste Webtest
[TestFixture] <br/>public class ErsterTest : IDisposable <br/>{ <br/> private SimpleServerStarter server; <br/> private Browser browser; <br/><br/> public ErsterTest() <br/> { <br/> server = new SimpleServerStarter(); <br/> server.StartServer(); <br/> StartUp().Wait(); <br/> } <br/><br/> private async Task StartUp() <br/> { <br/> browser = await Puppeteer.LaunchAsync(<br/> new LaunchOptions <br/> { <br/> Headless = false, <br/> ExecutablePath = @"C:\Program Files " +<br/> "(x86)\Microsoft\Edge\Application\" +<br/> "msedge.exe", <br/> IgnoreHTTPSErrors = true,<br/> // SSL-Zertifikatsfehler ignorieren <br/> }); <br/> } <br/><br/> [Test] <br/> public async Task Test1_ZaehleNachrichten() <br/> { <br/> var page = await browser.NewPageAsync(); <br/> await page.GoToAsync($"{_server.RootUri}"); <br/><br/> var rows = await page.EvaluateExpressionAsync<br/> &lt;int?&gt;("document.querySelectorAll(" +<br/> "'#messages li').length"); <br/> Assert.That(rows, Is.EqualTo(3)); <br/> } <br/><br/> public void Dispose() <br/> { <br/> _server.StopServer(); <br/> _browser.Dispose(); <br/> } <br/>}
Der Test selbst erzeugt zuerst eine neue Browser-Registerkarte und ruft die Website auf. Die Page-Methode EvaluateExpressionAsync<T>(string) führt den übergebenen String als JavaScript-Code aus und versucht, das Ergebnis als T (in diesem Fall int?) zu parsen. Dem AAA-Muster folgend wird der so erlangte Wert mit dem erwarteten Wert 3 verglichen.Was genau passiert nun in EvaluateExpressionAsync()? Auch für .NET-Entwickler mit wenig Erfahrung/Wissen über HTML und CSS lassen sich die meisten JavaScript-Zeilen für Puppeteer relativ leicht entwickeln. Nützlich ist dazu die Konsole von Chromium, die per [Strg]+[Umschalt]+[I] geöffnet werden kann. In Bild 5 ist oben die Website, in der Mitte der HTML-Code des Messages-Blocks und unten die Entwicklungskonsole zu sehen. In ihr lassen sich JavaScript-Befehle eingeben, die direkt darunter ausgewertet werden. Im Bild wurde document.querySelectorAll(’#messages li’) eingegeben und das Ergebnis ist die Anzeige einer NodeList, die li-Objekte enthält. Wird dieses JavaScript um .length ergänzt, ergibt sich 3 als Resultat. Eine Einführung in HTML/CSS-Selektoren würde den Rahmen des Artikels sprengen, eine Erklärung dieses Selektors finden Sie im Kasten Selektor kurz erklärt.
Die Chromium-Dev-Toolshelfen beim Entwickeln von Selektoren(Bild 5)
Autor
Warten, warten, warten
Eine häufige Fehlerquelle bei der Verwendung von Puppeteer (Sharp) sind fehlende Wartezeiten, in denen der Server antworten oder Chromium-Webseiten aufbauen kann. Um die Navigation abzuwarten, stehen die Werte der Enumeration WaitUntilNavigation zur Verfügung, die zum Beispiel als zweiter Parameter an Page.GotoAsync() übergeben werden können. Die Werte definieren Events, bis zu deren Eintreten gewartet werden soll. Die einzelnen Werte und ihre Bedeutung in der Reihenfolge des Auftretens sind:- DOMContentLoaded: Feuert, sobald das initiale HTML-Dokument geladen und geparst wurde (ohne Stylesheets, Bilder oder Sub-Frames).
- Load: Feuert, wenn alle abhängigen Dokumente geladen wurden (der Default-Wert, wenn der Parameter nicht angegeben wird).
- Networkidle2: Feuert, wenn 500 Millisekunden mit zwei oder weniger Netzwerkverbindungen vergangen sind.
- Networkidle0: Feuert, wenn 500 Millisekunden ohne Netzwerkverbindung vergangen sind.
Ein End-to-End-Test
Nach dem Navigieren auf Seiten und dem Auslesen von Werten fehlt noch das Interagieren mit den Inhalten der Webseite, um einen End-To-End-Test schreiben zu können. Im letzten Testszenario sollen zwei Einträge zum Message Board hinzugefügt und geprüft werden, ob die Anzahl der Nachrichten anschließend 5 ist. Listing 4 zeigt den dafür nötigen Code. Im Test selbst wird zweimal die Methode ErgaenzeEintrag() aufgerufen, der Rest gleicht dem ersten Test aus Listing 3 – mit dem Unterschied, dass der erwartete Wert nun 5 ist.Listing 4: Ein erster End-To-End-Test
[Test] <br/>public async Task ErgaenzgeZweiNachrichten() <br/>{ <br/> var page = await _browser.NewPageAsync(); <br/> await page.GoToAsync(_server.RootUri); <br/> await ErgaenzeEintrag(page, "Erster neuer Eintrag"); <br/> await ErgaenzeEintrag(page,<br/> "Zweiter neuer Eintrag"); <br/> var rows = await page.EvaluateExpressionAsync&lt;int?&gt;<br/> ("document.querySelectorAll('#messages li')." +<br/> "length"); <br/><br/> Assert.That(rows, Is.EqualTo(5)); <br/>} <br/><br/>private async Task ErgaenzeEintrag(Page page,<br/> string message) <br/>{ <br/> var options = new WaitForSelectorOptions {Hidden =<br/> false, Timeout = 5000, Visible = true}; <br/> var textBoxHandle = await page.WaitForSelectorAsync(<br/> "[name='Message.Text']", options); <br/><br/> await textBoxHandle.TypeAsync(message); <br/><br/> var navigationOptions = new NavigationOptions {<br/> WaitUntil = new[] { WaitUntilNavigation.Load }<br/> }; <br/> var navigationTask = page.WaitForNavigationAsync(<br/> navigationOptions); }); <br/><br/> var buttonHandle = await page.QuerySelectorAsync(<br/> "#addMessageBtn"); <br/> await buttonHandle.ClickAsync(); <br/> await navigationTask; <br/>}
In ErgaenzeEintrag() wird mittels WaitForSelectorAsync() darauf gewartet, dass ein HTML-Objekt geladen werden kann, das ein Attribut name mit dem Wert Message.Text enthält. Das Objekt muss sichtbar sein und falls es innerhalb von fünf Sekunden nicht geladen wird, schlägt der Test fehl. Die Methode WaitForSelectorAsync() gibt ein ElementHandle-Objekt zurück. Über dieses kann aus C# heraus mit HTML-Objekten gearbeitet werden. Dies passiert in der nachfolgenden Zeile, indem der Wert aus der Variable message in die Box getippt wird. Das ist fast wörtlich zu nehmen; der Wert wird nicht durch eine einfache DOM-Manipulation gesetzt, sondern virtuell eingetippt. Dadurch ist es möglich, auch Fehler wie eine TextBox im Read-only-Modus zu finden.Die beiden folgenden Zeilen dienen dem Warten auf die fertig geladene Webseite. navigationTask muss zuerst gestartet werden und meldet Vollzug, wenn die Seite das nächste Mal geladen wird und das Load-Ereignis feuert. So lässt sich in diesem Beispiel herausfinden, dass die Webseite fertig geladen wurde und bereit ist für weitere Interaktionen.buttonHandle istauch ein ElementHandle-Objekt. Hier kommt jedoch QuerySelectorAsync() ins Spiel. Die Methode wartet nicht auf ein Objekt, sondern geht davon aus, dass das Objekt vorhanden ist; andernfalls erzeugt sie einen Fehler (Sie ahnen es: WaitForSelectorAsync() ruft letztlich QuerySelectorAsync() auf, sofern das Objekt gefunden wird). Der Button wird mittels ClickAsync() aktiviert.Wichtig ist, dass die Reihenfolge hier exakt eingehalten wird, da ClickAsync() nur zurückmeldet, dass der Klick erfolgt ist, und nichts über den aktuellen Zustand der Webseite aussagt. Um eine Race Conditon zu vermeiden, muss navigationTask unbedingt vorher gestartet und nach ClickAsync() mit await erwartet werden.
Fazit und Ausblick
Der Artikel hat einen kleinen Einblick in die Möglichkeiten und Fallstricke von Puppeteer (Sharp) gegeben. Bis zum „Master of Puppets“ ist es noch ein weiter Weg, aber der erste Schritt ist getan. Wer sich tiefer in das Thema Oberflächentests mit Puppeteer einarbeiten will, kann auf das Buch „UI Testing with Puppeteer“ von Dario Kondratiuk zurückgreifen [10], der gleichzeitig auch Autor von Puppeteer Sharp ist. Der Schwerpunkt des Buchs liegt auf Node.js und Puppeteer, das meiste lässt sich jedoch relativ einfach auf Puppeteer Sharp übertragen.Wie anfangs erwähnt, ist das Testen von grafischen Oberflächen nicht der einzige Einsatzzweck von Puppeteer. In den nächsten beiden Ausgaben der dotnetpro geht es um PDF-Erzeugung und Web-Crawling.Fussnoten
- Mike Cohn, The Forgotten Layer of the Test Automation Pyramid, http://www.dotnetpro.de/SL2107PuppeteerSharp1
- Puppeteer Sharp, http://www.dotnetpro.de/SL2107PuppeteerSharp2
- Statista, Marktanteile der führenden Browserfamilien an der Internetnutzung in Deutschland von Januar 2009 bis März 2021, http://www.dotnetpro.de/SL2107PuppeteerSharp3
- Puppeteer API v1.11.0, http://www.dotnetpro.de/SL2107PuppeteerSharp4
- Chrome DevTools Protocol, http://www.dotnetpro.de/SL2107PuppeteerSharp5
- AspNetCore.Docs: AspNetCore.Docs, http://www.dotnetpro.de/SL2107PuppeteerSharp6
- NUnit, https://nunit.org
- Microsoft Docs, Unit test basisc – Write your tests, http://www.dotnetpro.de/SL2107PuppeteerSharp7
- Puppeteer waitUntil Options, http://www.dotnetpro.de/SL2107PuppeteerSharp8
- Dario Kondratiuk, UI Testing with Puppeteer, ISBN 978-1-800-20678-6,
- Selfhtml, JavaScript/DOM/Document, http://www.dotnetpro.de/SL2107PuppeteerSharp9
- Selfhtml, CSS/Tutorials/Selektoren, http://www.dotnetpro.de/SL2107PuppeteerSharp10
