en
de

Scenarioo: Automatisierte Dokumentation mit User Interface Tests

30 Juni 2015
| |
Lesezeit: 9 Minutes

Seien wir ehrlich: Software zu dokumentieren ist mühsam und teuer. Niemand hat Zeit die Dokumentation aktuell zu halten, also wird sie wertlos. Ohne verlässliche Dokumentation wiederum ist die effiziente Weiterentwicklung eines umfangreichen Systems schwierig. Viele Personen sind am Betrieb, dem Support und der Weiterentwicklung beteiligt. Sie brauchen eine verlässliche Informationsquelle über den aktuellen Funktionsumfang. Mit dem Open Source Projekt Scenarioo [1] gehen wir dieses Problem auf neue Art an. Wir generieren Dokumentation für Frontend-Systeme zu hohem Grad automatisiert aus User Interface Tests. Diese Dokumentation ist immer aktuell, für alle zugänglich, einfach verständlich und bildet eine Brücke zwischen Business und IT als ideale Grundlage für effizientere Zusammenarbeit und Kommunikation.

Time-to-Market für neue Features und Kosteneffizienz sind wichtige Erfolgsfaktoren der Softwareentwicklung. Das Motto „working software over comprehensive documentation“ hat sich deshalb in der agilen Software-Entwicklung richtigerweise durchgesetzt. Die Kosten für die manuelle Pflege und Aktualisierung von umfangreicher Dokumentation stehen in der Regel kaum in einem gesunden Verhältnis zum tatsächlichen Nutzen. Wie aber kann verhindert werden, dass die Software-Entwicklung in Folge fehlender oder unvollständiger Dokumentation ineffizient wird? Wie stellen Sie sicher, dass jemand Ihre Software auch noch in ein paar Jahren versteht, so dass neue Funktionalitäten darin effizient eingebaut werden können?

Das Problem: viele Beteiligte, viele Fragen

Zu Beginn ist meistens alles noch verhältnismässig einfach. Die zwei Entwicklungsteams à je sieben Entwickler und je zwei Business Analysten, der Product Owner und die drei beteiligten Product Manager kennen die Funktionen der Software in- und auswendig. Der Funktionsumfang ist überschaubar und alle an der Entwicklung beteiligten Personen sind noch für Rückfragen verfügbar. Neue Wünsche von Benutzern und Business können relativ schnell umgesetzt werden und das System wird immer komplexer. Nach ein bis zwei Jahren wird die Situation schwieriger. Der Funktionsumfang ist grösser und nicht mehr so einfach zu durchblicken. Viele Personen, welche an der Entwicklung beteiligt waren, haben das Projekt oder gar die Firma verlassen. Die Dokumentation ist lückenhaft und nicht auf dem aktuellsten Stand. Sie zu aktualisieren ist kostspielig und zeitaufwändig. Neue Funktionalitäten sollen schnellst möglich umgesetzt werden. Es geht jedoch viel Zeit damit verloren, das bestehende System zu verstehen und zu entscheiden welche Funktionalitäten wie ergänzt, erweitert oder angepasst werden müssen. Selbst das Entwicklungsteam muss hierbei unterstützen und viele Anfragen beantworten, wie das aktuelle System funktioniert. Dies ist ineffizient und bremst die Weiterentwicklung des Systems aus.

Die folgenden Beispiele zeigen ein paar typische Fragestellungen, mit denen wir in Projekten oft konfrontiert werden:

  • Wie funktioniert der Use Case „Produkt bestellen“?
  • Welche typischen Benutzerabläufe durch diesen Use Case unterstützt die Software?
  • Wie sehen diese Abläufe aus? Aus welchen Interaktions-Schritten und UI-Masken bestehen diese Abläufe?
  • Welche Spezialfälle werden unterstützt? Wie sehen diese aus?
  • Könnt ihr mir aktuelle Screenshots vom Use Case „neues Benutzerkonto eröffnen“ senden?
  • Was für mögliche Varianten der UI Maske „Bezahlen“ gibt es im Use Case „Produkt bestellen“ für die verschiedenen Kundenarten?
  • Welche Umsysteme werden beim Benutzer-Login aufgerufen?
  • In welchen Use Cases wird der Webservice „GetDiscountForProduct“ überall aufgerufen und in welchen Prozess-Schritten?

Im besten Fall können die Fragen durch Ausprobieren auf einem Testsystem oder durch Recherche im Code mit etwas Aufwand beantwortet werden. Oft fehlt aber entweder ein Zugang zu einem geeigneten Testsystem, die geeigneten Testdaten oder schlichtweg das Knowhow wie interagiert werden muss um ein spezielles Szenario zu provozieren. Der Quellcode wiederum ist nicht für alle Beteiligten verfügbar, geschweige denn verständlich.

Die Lösung: User Interface Tests und automatisierte Dokumentation mit Scenarioo

Wir haben festgestellt, dass automatisierte User Interface Tests ein probates Mittel sind um die Funktionen einer Software auf UI-Interaktions-Ebene nicht nur zu testen sondern auch zu dokumentieren. Bei Softwaresystemen mit komplexeren Benutzerschnittstellen werden UI Tests bereits häufig zur Qualitätssicherung und für Regressionstests eingesetzt. Leider leben diese Tests oft ein Schattendasein und sind nur für Entwickler oder Tester sichtbar, verständlich und nützlich. Mit dem von Zühlke-Mitarbeitern entwickelten Open Source Projekt Scenarioo erhöhen wir den Nutzen dieser Tests zusätzlich, indem wir sie für alle Beteiligten im Projekt sichtbar machen. So entsteht eine anschauliche Dokumentation der Funktionalitäten einer Software mit jederzeit aktuellen Bildern der UI Masken.

Das folgende Übersichtsbild zeigt den grundlegenden Aufbau und Ablauf um eine automatisierte Dokumentation aus UI Tests mit Scenarioo zu erstellen und zu nutzen. Die darauf folgenden Abschnitte erklären die einzelnen Schritte und Teile der Dokumentation mit Scenarioo im Detail.

Scenarioo-Dokumentations-System

Scenarioo-Dokumentations-System

Schritt 1 – Schreiben und Strukturieren der UI Tests

Für jeden Use Case, den die Software unterstützt, werden die wichtigsten und für die Dokumentation relevanten Benutzerszenarien mit je einem Test Case beschrieben und getestet. Dies kann im Prinzip in einer beliebigen UI-Testtechnologie erfolgen. In unseren Webprojekten hat sich dabei Selenium bewährt. Der Ansatz funktioniert auch mit Testtechnologien für Desktop- oder Mobile-Applikationen.

Das folgende Beispiel zeigt, wie die Testfälle eines so getesteten Use Cases in der Scenarioo Dokumentation schliesslich in der Use Case Übersicht dargestellt werden.

Übersicht über die Szenarien eines Use Cases

Übersicht über die Szenarien eines Use Cases

Essentiell ist dabei, dass die UI Tests für die Dokumentation sinnvoll strukturiert werden. Dabei hat sich als Grundstruktur die Gruppierung in Use Cases bewährt. Pro Use Case beschreiben wir die wichtigsten Test Cases. Jeder Testfall beschreibt ein essentielles Benutzerszenario, also einen vollständigen Benutzerablauf durch den Use Case. Typischerweise gibt es ein Hauptszenario mit dem grundlegendsten Ablauf und mehrere weitere alternative Szenarien mit speziellen Abläufen und auch Fehlerfällen. Mit Hilfe von sogenannten „Labels“ können die Szenarien für die Dokumentation markiert und gruppiert werden. So wird typischerweise ein Label „Happy“ für das Hauptszenario vergeben und z.B. „Error“ für Fehlerfälle. Es können beliebige weitere Labels vergeben werden.

Es ist ausserdem wichtig, nur die essentiellen und für die Dokumentation relevanten Benutzerszenarien auszuwählen und zu testen. Sowohl Tests wie auch Dokumentation sollen in einem gesundem Mass erstellt werden und zwar so, dass die wesentlichen Benutzerszenarien abgedeckt sind. Hier schlagen wir also zwei Fliegen mit einer Klappe, weil eine sinnvolle Testabdeckung mit einer sinnvollen Dokumentation sehr gut Hand in Hand geht. Pro Use Case bedeutet das in der Regel nicht mehr als 3-15 Test-Szenarien, je nach Komplexität eines Use Cases. Falls das nicht reicht, sollte man prüfen, ob die gewählten Use Cases in der Dokumentation sinnvoll geschnitten sind. Ausserdem ist zu vermeiden, dass komplexe Businessregeln fälschlicherweise in UI-Tests getestet werden, anstatt in dafür besser geeigneten Unit Tests. Dies ist generell ein wichtiges Design Prinzip für UI Tests, auch im Sinne der Test-Pyramide [3].

Schritt 2 – Automatische Generierung der Dokumentation

Auf einem automatisierten Buildsystem (z.B. Jenkins, Team City, u.a.) werden die Tests mindestens jede Nacht ausgeführt und automatisch validiert. Während der Ausführung wird auch die Dokumentation erstellt. Bei jedem Interaktionsschritt wird ein Bild des User Interfaces der Applikation erstellt und abgelegt. Zusätzlich werden weitere Informationen in XML-Dateien zu jedem Schritt, Szenario und Use Case abgelegt. Dies erfolgt durch den Einbau von entsprechenden Hooks in den Tests, welche mit Hilfe der Scenarioo Docu Writer Library die Dokumentationsdaten als Dateien im Scenarioo-Format ablegen. Jede Nacht entsteht so eine aktualisierte Dokumentation.

Auswahl zwischen mehreren Dokumentations-Build-Ständen in Scenarioo

Auswahl zwischen mehreren Dokumentations-Build-Ständen in Scenarioo

Mehrere Dokumentationsstände (=Builds) werden archiviert. Dies ermöglicht es in der Scenarioo-Dokumentation auch ältere Versionen zu betrachten oder zu vergleichen. Zusätzlich werden mehrere Dokumentationen für verschiedene Entwicklungsstände (=Branches) erzeugt. Dadurch kann zum Beispiel der aktuelle Stand des letzten produktiven Releases (inklusive allfälliger Bugfixes) mit dem aktuellen Entwicklungsstand oder mit speziellen Featurebranches verglichen werden.

Schritt 3 – Zugriff auf die Dokumentation mit der Webapplikation Scenarioo

Das Herzstück von Scenarioo ist die Webapplikation, welche die generierten Dokumentationsdaten aus den Builds für alle Beteiligten anschaulich präsentiert und benutzerfreundlich navigierbar macht. Wie in einem Bilderbuch können die einzelnen Benutzerszenarien Schritt für Schritt betrachtet werden. Es kann durch die Use Cases und ihre Szenarien navigiert werden. Beliebige verknüpfte Zusatzinformationen können betrachtet werden. Alle Informationen können komfortabel durchsucht werden, damit der Betrachter möglichst schnell auf seine gewünschten Use Cases, Szenarien, Screens und weitere Informationen zugreifen kann.

Die folgenden Bilder zeigen die wichtigsten Ansichten für ein Szenario und einen Schritt des Szenarios am Beispiel des Use Cases „Seite suchen auf Wikipedia“:

Übersicht über die Screens in einem Benutzerszenario in der Scenarioo Webapplikation

Übersicht über die Screens in einem Benutzerszenario in der Scenarioo Webapplikation

Detailansicht eines Schritts in einem Szenario

Detailansicht eines Schrittes in einem Szenario

Dieses Beispiel einer Dokumentation der Wikipedia-Webapplikation stammt aus der Demo von Scenarioo. Das vollständige Beispiel kann hier mit der Scenarioo-Webapplikation detailliert betrachtet und durchsucht werden:
http://demo.scenarioo.org

Das Scenarioo Dokumentationsmodell

Das folgende Diagramm zeigt als Zusammenfassung eine Übersicht über das Scenarioo Dokumentationsmodell.

Das Dokumentations-Modell von Scenarioo

Das Dokumentations-Modell von Scenarioo

  • Branch: Verschiedene Produktversionen, Releases oder gar Featurebranches können so separat dokumentiert werden.
  • Build: In jedem Branch können mehrere Dokumentationsversionen abgelegt werden (typischerweise jede Nacht). Jeder Build hat eine Version und einen Zeitstempel.
  • Use Case: Die getesteten und dokumentierten Use Cases.
  • Scenario: Die eigentlichen Testfälle zeigen pro Use Case die relevanten Benutzerszenarien.
  • Step: Dies sind die einzelnen Interaktions-Schritte eines Benutzer-Szenarios.
  • Screenshot: Jeder Step wird mit einem Screenshot dokumentiert.
  • Page: Typischerweise passieren die Interaktions-Schritte auf einer Page (das kann eine Webseite, eine UI-Maske, eine View, etc. sein). Mehrere Schritte auf der gleichen Page werden in Scenarioo zusammen gruppiert dargestellt.
  • Label (=Tag): Ein Label ist ein angehängtes Schlagwort, damit können die Use Cases, Szenarien und sogar die einzelnen Schritte speziell markiert und kategorisiert werden.
  • Details (=beliebige weitere Zusatzinformationen): Auf jedem Schritt können beliebige Zusatzinformationen abgelegt werden, wie z.B. HTML-Code, Benutzer-Rolle, Test-Konfiguration, Umsystem-Aufrufe, Link zum Sourcecode, Link zu anderen Dokumentationen. Hierfür stehen generische Objekt-Strukturen zur Verfügung. Ebenso können solche Zusatzinformationen auch an anderen Objekten (z.B. am Use Case oder Szenario) in der Dokumentation angehängt werden.

Grenzenlose Möglichkeiten: Vieles lässt sich so dokumentieren

Scenarioo setzt praktisch keine Grenzen, welche Informationen alle automatisiert in der Dokumentation abgelegt oder verknüpft werden können. So haben wir zum Beispiel in einigen Projekten folgende hilfreichen Informationen darin abgelegt oder verknüpft und so für alle verfügbar gemacht:

  • Ausgangslage für ein Test-Szenario: Konfiguration des Testsystems, Testdaten, Benutzer-Rolle etc.
  • Aufrufe von Umsystemen oder internen Komponenten in jedem Schritt eines Szenarios, aufgrund von Introspektion oder Logging während der Testausführung
  • Backlog-Items, welche die dokumentierten Benutzerszenarien (=Testfälle) ursprünglich spezifiziert resp. beeinflusst haben.
  • Verknüpfung mit anderen Dokumentationen oder Informationsquellen (Umsysteme, Wiki, Quellcode, etc.)

Ein Puzzleteil im Living Documentation System

Scenarioo ist natürlich nur ein Puzzleteil in der Living Documentation ihres Softwaresystems, im Sinne von „Specification by Example“ gemäss Buch von Gojko Adzic [2]. Die Scenarioo-Dokumentation beschreibt lediglich den Ist-Zustand der Funktionalitäten einer Software auf Ebene der UI-Interaktionen. Deshalb kombiniert man Scenarioo sinnvollerweise mit anderen Tools zu einem Living Documentation System. Hier seien deshalb noch ein paar weitere bewährte Tools erwähnt, die sich mit Scenarioo kombinieren lassen:

  • Wiki für manuelle High-Level-Dokumentation und Verlinkung in die anderen Doku-Tools
  • Modellierungs-Tools, wie z.B. Sparx Enterprise Architect für die High-Level System Architektur und Prozess-Übersichten
  • Backlog oder Task Management System mit Product Backlog Items, wie z.B. User Stories
  • BDD-Tools für detailliertere Business-Logik-Dokumentation anhand von Komponenten-Tests
  • Javadoc und andere Tools für API Dokumentationen

Bei Zühlke setzen wir uns in der Fokusgruppe „Specification by Example“ gezielt damit auseinander, wie wir unsere Softwarelösungen durch geschickte Kombination solcher Tools und moderner Requirements Engineering Methoden möglichst effizient und effektiv spezifizieren und dokumentieren können.

Fazit: Vielfältiger Nutzen

Mit Hilfe einer automatisierten Scenarioo-Dokumentation konnte in unseren Projekten der Aufwand für manuelle Dokumentation reduziert werden. Gleichzeitig wurde das Entwicklungsteam entlastet, weniger Nachforschung betreiben zu müssen um Fragen von beteiligten Personen zu beantworten. So kann sich das Entwicklungsteam wieder auf die Entwicklung von neuen Features konzentrieren.

Dank der Scenarioo-Dokumentation sind die User Interface Tests nun für alle Beteiligten sichtbar. Requirements Engineers, Business Analysten, Product Manager, Product Owner und Tester können so die Tests einfach reviewen und wertvollen Feedback zu den automatisierten UI Tests geben. Dies trägt zur Verbesserung der Qualität der Tests bei. Auch Fachanwender oder Fachexperten können schon Feedback zu neuen Funktionalitäten geben noch bevor diese für sie auf einem Testsystem verfügbar sind. So können allfällige Missverständnisse schneller entdeckt und ausgeräumt werden. Selbst das Entwicklungsteam verwendet die Scenarioo Dokumentation häufig. So kann ein Entwickler zum Beispiel über Scenarioo einen schnellen Zugang zu einem anzupassenden User Interface finden oder etwa auch prüfen, ob bei der Weiterentwicklung versehentlich etwas an der Darstellung verändert wurde.

Nun haben endlich alle Beteiligten Zugriff auf eine gemeinsame und aktuelle Dokumentation der umgesetzten Funktionalitäten. Dies ist ein nützliches Hilfsmittel für Kommunikation und Kollaboration rund um die Weiterentwicklung und den Betrieb der Software und schliesslich zur Steigerung der Produktivität.

Haben wir Ihr Interesse für Scenarioo und automatisierte Dokumentation geweckt? Was denken Sie über diesen Ansatz? Wäre eine Scenarioo-Dokumentation auch in Ihrem Projekt hilfreich? Oder wie stellen Sie sicher, dass alle Beteiligten einfachen Zugang zum nötigen Knowhow über die aktuellen Systemfunktionalitäten haben?

Wir sind gespannt auf Ihre Reaktionen und freuen uns auch über Fragen. Gerne werden wir diesen Input in kommenden Blog-Beiträgen aufgreifen. Bald wollen wir hier nämlich mehr über Scenarioo erzählen und wie man ein solches Dokumentationssystem im Detail aufbaut.

 

Weiterführende Links

[1] Scenarioo, Open Source Projekt: http://www.scenarioo.org
[2] Specification by Example, Buch von Gojko Adzic: http://specificationbyexample.com
[3] Test-Pyramide, Blog-Beitrag von Franziska Meyer: https://www.zuehlke.com/blog/pyramide-oder-kuehlturm

Kommentare (0)

×

Updates

Schreiben Sie sich jetzt ein für unsere zwei-wöchentlichen Updates per E-Mail.

This field is required
This field is required
This field is required

Mich interessiert

Select at least one category
You were signed up successfully.