Agiles Testen von JIRA Plugins (Teil 3): Systemtests

Nach Unit- and Wired Tests stellen Systemtests einen weiteren Testtyp der Testpyramide dar, den wir im Kontext der Plugin Entwicklung für JIRA betrachten wollen. In diesem Artikel werden wir – d.h. Raimar Falke und ich – zwei weitere Testarten vorstellen, die die gesamte bzw. nahezu die gesamte Applikation testen: Tests der Weboberfläche und REST-API Tests.

Hinweis: Dies ist eine 4-teilige blog Serie. Agiles Testen von JIRA Plugins (Teil 1) , Wired Tests (Teil 2) , Systemtests (Teil 3) , CI Server Integration und Test Coverage (Teil 4) . Darüber hinaus finden Sie auch eine Einführung zum Thema JIRA mit Plugins erweitern in unserem blog.

Testen der Weboberfläche

Atlassian stellt eine Reihe von Tools bereit, die die Erstellung von End-to-End Tests für ihre Produkte vereinfacht. Die wichtigsten darunter sind TestKit, welches die Erstellung eines „Backdoor“ vornimmt, welcher für die Durchführung administrativer Aufgaben oder das Einspielen von Testdaten genutzt werden kann, sowie eine große Zahl an Pageobjects für alle Applikationen. Auch wenn TestKit nicht genutzt werden muss, ist die Verwendung sehr zu empfehlen, da es viele Aufgaben, wie bspw. das Erzeugen eines definierten Zustands der zu testenden Instanz zum Kinderspiel macht. Ein weiteres Tool für die Entwicklung von End-to-End Tests, welches TestKit stark ähnelt, ist FuncTest . Der wichtigste Unterschied ist, dass FuncTest Selenium für die Ausführung administrativer Aufgaben nutzt, während TestKit dies über eine REST-API erledigt.

Setup

Die Definition der benötigten Dependencies ist einfach und sieht typischerweise so aus:

1<dependency>
2  <groupId>com.atlassian.jira.tests</groupId>
3  <artifactId>jira-testkit-client</artifactId>
4  <version>${testkit.version}</version>
5  <scope>test</scope>
6</dependency>
7 
8<dependency>
9  <groupId>com.atlassian.jira</groupId>
10  <artifactId>atlassian-jira-pageobjects</artifactId>
11  <version>${jira.version}</version>
12  <scope>test</scope>
13  <exclusions>
14    <!-- excluded due to clash with other SLF implementation -->
15    <exclusion>
16      <artifactId>slf4j-simple</artifactId>
17      <groupId>org.slf4j</groupId>
18    </exclusion>
19  </exclusions>
20</dependency>

Beim Versuch, Seleniumtests auf einem System mit einem 64-Bit Linux, z.B. einem CI Server in einer AWS EC2 Instanz, auszuführen, wird man jedoch Probleme bekommen. Der Grund dafür ist, dass das SDK seine eigenen Browser mitbringt, unter anderem einen Firefox 12. Dieser hat jedoch ein bekanntes Problem auf 64-Bit Linux Systemen. Die Lösung besteht darin, explizit eine neuere Version von Selenium inklusive der zugehörigen Atlassian Browser als Dependency zu benutzen:

1<!-- the following dependencies are needed only for running on 64bit Linux, 
2     since the default Firefox 12 has problems -->
3<dependency>
4  <groupId>com.atlassian.browsers</groupId>
5  <artifactId>atlassian-browsers-auto</artifactId>
6  <version>2.3.2</version>
7  <scope>test</scope>
8</dependency>
9 
10<dependency>
11  <groupId>org.seleniumhq.selenium</groupId>
12  <artifactId>selenium-java</artifactId>
13  <version>2.25.0</version>
14  <scope>test</scope>
15</dependency>

Der letzte Schritt bei der Vorbereitung der Projekts besteht darin, das TestKit Plugin in der JIRA-Testinstanz zu aktivieren. Dies kann man entweder durch eine Property in der POM oder durch Hinzufügen des Plugins in der Konfiguration des JIRA Builds erreichen.

• Als Property:

1<prroperties>
2  ...
3  <plugins>com.atlassian.jira.tests:jira-testkit-plugin:${testkit.version}</plugins>
4  ...
5</properties>

• Als Plugin Artefakt in der AMPS Plugin Konfiguration:

1<plugin>
2  <groupId>com.atlassian.maven.plugins</groupId>
3  <artifactId>maven-jira-plugin</artifactId>
4  <version>${amps.version}</version>
5  <extensions>true</extensions>
6  <configuration>
7    ...
8    <pluginArtifacts>
9      ...
10      <pluginArtifact>
11        <groupId>com.atlassian.jira.tests</groupId>
12        <artifactId>jira-testkit-plugin</artifactId>
13        <version>${testkit.version}</version>
14      </pluginArtifact>
15    </pluginArtifacts>
16  </configuration>
17</plugin>

Tests schreiben

Das Artefakt für die JIRA Pageobjects stellt verschiedene Mittel bereit, die eine effektive Implementierung von UI Tests unterstützen. Zunächst stellt es eine abstrakte Klasse (AbstractJiraPage ) für alle (eigenen) Pageobjects bereit, die ein Grundgerüst für die Implementierung bietet. Wenn man die Klasse erweitert, müssen die Methoden getUrl() und isAt() implementiert werden: getUrl() liefert die URL zurück, zu der navigiert werden muss, um die Seite zu laden, die durch das Pageobject repräsentiert wird; isAt() prüft, ob die Seite auch korrekt geladen ist (bspw. durch Prüfung, dass ein bekanntes Element sichtbar ist). Dabei wird grundsätzlich angenommen, dass ein Element nicht unbedingt sofort verfügbar ist. Zusätzlich stellt die abstrakte Klasse eine PageBinder -Instanz bereit, die es ermöglicht, die aktuell geladene Seite an ein Pageobject zu binden, inklusive der auf der Seite enthaltenen Elemente. Ein Beispiel für ein Pageobject kann also folgendermaßen aussehen:

1package pages;
2 
3import com.atlassian.jira.pageobjects.pages.AbstractJiraPage;
4import com.atlassian.pageobjects.elements.ElementBy;
5import com.atlassian.pageobjects.elements.PageElement;
6import com.atlassian.pageobjects.elements.query.TimedCondition;
7 
8public class FooBarPage extends AbstractJiraPage {
9  @ElementBy(id ="save") private PageElement saveButton;
10  @ElementBy(id ="some-input") private PageElement someInput; 
11 
12  @Override
13  public String getUrl() {
14    return"/secure/admin/foo-bar.jspa";
15  }
16 
17  @Override
18  public TimedCondition isAt() {
19    return someInput.timed().isVisible();
20  }
21 
22  public FooBarPage save() {
23    saveButton.click();
24    return pageBinder.bind(FooBarPage.class);
25  }
26 
27  public void setSomeInput(String input) {
28    someInput.type(input);
29  }
30 
31  public String getSomeInput() {
32    return someInput.getValue();
33  }
34}

Die eigentlichen UI Tests müssen in einem Package mit Präfix it.* liegen, da sie als Integrationstests eine laufende JIRA Instanz benötigen. Ein Beispiel für einen Test, der FuncTest benutzt, sieht folgendermaßen aus:

1package it.foo.bar;
2 
3import static org.hamcrest.CoreMatchers.is;
4import static org.junit.Assert.assertThat;
5import org.junit.Test;
6import pages.FooBarPage;
7import com.atlassian.jira.functest.framework.FuncTestCase;
8import com.atlassian.jira.pageobjects.JiraTestedProduct;
9import com.atlassian.jira.pageobjects.config.EnvironmentBasedProductInstance;
10import com.atlassian.jira.testkit.client.Backdoor;
11import com.atlassian.jira.testkit.client.util.TestKitLocalEnvironmentData;
12 
13public class FooBarPageTest extends FuncTestCase {
14  // the setupUpTest() method sets this
15  private JiraTestedProduct jira;
16 
17  @Override
18  protected void setUpTest() {
19    super.setUpTest();
20    Backdoor backdoor = new Backdoor(new TestKitLocalEnvironmentData());
21    backdoor.restoreBlankInstance();
22    jira = new JiraTestedProduct(new EnvironmentBasedProductInstance());
23  }
24 
25  @Test
26  public void test_that_save_works() {
27    FooBarPage page = jira.gotoLoginPage().loginAsSysAdmin(FooBarPage.class);
28 
29    page.setSomeInput("my input");
30    page.save();
31 
32    jira.gotoHomePage();
33    page = jira.goTo(FooBarPage.class)
34    assertThat(page.getSomeInput(),is("my input"));
35  }
36}

Tests ausführen

Frontend Tests werden ganz normal als Integrationstests betrachtet und ausgeführt. Wenn man jedoch wie im obigen Beispiel FuncTest benutzt, muss man mit einer kleinen Überraschung rechnen: die Tests scheitern, wenn man nicht ein (leeres) Verzeichnis src/test/xml im Projekt angelegt hat. Eine Alternative (die wir auch empfehlen), ist auf die Verwendung von FuncTest zu verzichten. Der Test erweitert dann keine Klasse mehr (sieht man von der impliziten Vererbung von java.lang.Object ab) und die Methode setUpTest aus dem Beispiel ist folgendermaßen umzuschreiben:

1@Before
2public void setUp() {
3  jira = TestedProductFactory.create(JiraTestedProduct.class);
4  Backdoor backdoor = new Backdoor(
5    new ProductInstanceBasedEnvironmentData(jira.getProductInstance()));
6  backdoor.restoreBlankInstance();
7}

REST-API Tests

Auch wenn UI Tests sowohl den Java-Code des Servers als auch den Javascript (und HTML) Code auf dem Client testet, sind sie für ihren hohen Implementierungs- und Wartungsaufwand und die lange Ausführungsdauer (im Vergleich zu anderen Testarten) bekannt. Eine Alternative für den Test der Serverseite stellen Tests der vom Server bereitgestellten API dar. Im Fall von JIRA ist das eine REST-API. Wie sich herausstellt, gibt es bei der Implementierung von REST-API Tests für JIRA keine großen Besonderheiten zu beachten. Da es sich ebenfalls um Integrationstests handelt, müssen sie wie UI Tests in einem Package mit Präfix it.* liegen. Das Framework für die Entwicklung der Tests kann frei gewählt werden. Aus unserer Erfahrung können wir den Einsatz von REST Assured empfehlen. Danach gibt es nur zwei Dinge, die zu erwähnen sind:

1. Wird der Test im Rahmen des Maven-Builds ausgeführt, wird durch das SDK eine System-Property “baseurl” gesetzt, die auf die laufende Testinstanz verweist. Startet man den Test jedoch aus der IDE, ist die Property nicht gesetzt. Als Fallback sollte man sie daher im Test selbst setzen, bspw. auf „http://localhost:2990/jira“.
2. Die Authentifizierungsmethode sollte auf präemptiv gesetzt werden, da JIRA statt Statuscode 401 (Unauthorized) den Code 200 (Ok) zurücksendet, auch wenn eine Authentifizierung benötigt wird. Aus diesem Grund kann die automatische Authentifizierung im Fehlerfall, wie sie üblich ist, nicht verwendet werden.

Ein Teil eines Testsetups könnte daher folgendermaßen aussehen:

1String urlPrefix = System.getProperty("baseurl", "http://localhost:2990/jira");
2  RestAssured.baseURI = urlPrefix + urlSuffix;
3 
4  PreemptiveBasicAuthScheme authScheme = new PreemptiveBasicAuthScheme();
5  authScheme.setUserName(username);
6  authScheme.setPassword(password);
7  RestAssured.authentication = authScheme;

Zusammenfassung

Die Implementierung von seleniumbasierten Frontendtests benötigt nur wenige spezifische Anpassungen an JIRA und auch die lokale Ausführung der Tests ist einfach. Das Ganze sieht etwas anders aus, wenn man die Tests auf einem CI Server ausführen möchte. Tests der REST-API sind im Gegensatz dazu weniger problematisch, sind einfacher zu implementieren und laufen auch schneller. Wir empfehlen sie daher als zweite Testart nach Unittests. Hat das Projekt einen große Menge an eigenem Javascript oder muss eine breites Spektrum an Browsern oder Betriebssystemen zuverlässig bedient werden, lohnt sich evtl. auch die Investition in die Entwicklung von Oberflächentests.

Im nächsten Artikel dieser Serie werfen wir einen Blick auf die Besonderheiten, die bei der Auführung von Tests in einem CI Server eine Rolle spielen.