Tests für eigene Plug-ins automatisieren (agorum.dev)

Das Modul agorum.dev enthält eine Testsuite für die Durchführung von automatisierten Tests, etwa für Workflows, Aktive Ordner und mehr. Eine testgetriebene Entwicklung (test driven development) verbessert die Qualität von Code.

Inhalt des Moduls

---

Mithilfe des Moduls können Sie:

• einen Test erstellen
• einen Test über die Testsuite ausführen
• einen Test basierend auf bereits gelaufenen Workflows automatisch erzeugen

Einen Test erstellen

---

Einen Test definieren Sie über ein Test-Skript auf eine von zwei Arten:

• über das Kontextmenü
• über die Kopfleiste

Einen Test über das Kontextmenü erstellen

1. Öffnen Sie links in der Seitenleiste Explorer.
2. Öffnen Sie Ihr Konfigurationsprojekt unter:

   Eigene Dateien/Administration/customers/<Konfigurationsprojekt>

3. Klicken Sie das Konfigurationsprojekt mit der rechten Maustaste an.
4. Wählen Sie im Kontextmenü Development > Create a test from template.
   
   Ergebnis: Der Dialog Create test script öffnet sich.
5. Vergeben Sie einen Namen für Ihr Skript.
6. Klicken Sie auf OK.
   
   Ergebnis:
   
   • Das Skript öffnet sich.

   Hinweis: Sie können das Skript an dieser Stelle nicht starten, sondern nur im Rahmen der Testsuite.

   • Das System legt das Skript automatisch an unter:

   Eigene Dateien/Administration/customers/<Konfigurationsprojekt>/test/js

7. Passen Sie das Skript an (siehe Aufbau eines Test-Skripts).
8. Speichern Sie das Skript.

Einen Test über die Kopfleiste erstellen

Erstellen Sie einen Test über die Kopfleiste, müssen Sie das Konfigurationsprojekt manuell wählen.

1. Klicken Sie oben rechts in der Kopfleiste auf und dann auf Development > Create a test from template
2. Wählen Sie Ihr Konfigurationsprojekt und vergeben Sie einen Namen für Ihr Skript.
3. Klicken Sie auf OK.
   
   Ergebnis:
   
   • Das Skript öffnet sich.

   Hinweis: Sie können das Skript an dieser Stelle nicht starten, sondern nur im Rahmen der Testsuite.

   • Das System legt das Skript automatisch an unter:

   Eigene Dateien/Administration/customers/<Konfigurationsprojekt>/test/js

4. Passen Sie das Skript an (siehe Aufbau eines Test-Skripts).
5. Speichern Sie das Skript.

Einen Test über die Testsuite ausführen

---

Sie führen einen Test über die Testsuite aus, um den Test aufzurufen. Die Testsuite öffnen Sie in Ihrem Konfigurationsprojekt.

1. Öffnen Sie links in der Seitenleiste Explorer.
2. Öffnen Sie Ihr Konfigurationsprojekt unter:

   Eigene Dateien/Administration/customers/<Konfigurationsprojekt>

3. Klicken Sie das Konfigurationsprojekt mit der rechten Maustaste an.
4. Wählen Sie im Kontextmenü Development > Test suite.
   
   Ergebnis:
   
   • Der Dialog Test suite: js öffnet sich.
   • Sie sehen links in einer Baumstruktur alle Test-Skripte, die sich innerhalb Ihres Konfigurationsprojekts befinden.

   Tipp: Klicken Sie innerhalb Ihres Konfigurationsprojekts ein bereits abgelegtes Test-Skript oder einen Ordner mit Test-Skripts mit der rechten Maustaste an, öffnen Sie die Testsuite nur für dieses eine Skript oder für die Skripte, die sich in diesem Ordner befinden.

5. Markieren Sie die gewünschten Tests oder klicken Sie auf Run all tests.
   
   Ergebnis: Das System führt die Skripte und Tests aus.
   
   • Sie sehen im Feld Status den Status des durchgeführten Tests.
   • Sie sehen in den Feldern Stacktrace und Result/Error Details zu einem eventuellen Fehlerstatus.
   
    
   

   Fehler beim Testen

Einen Test in der Testsuite bearbeiten

Sie können innerhalb der Testsuite in der Baumstruktur einen Test direkt bearbeiten.

1. Öffnen Sie die Testsuite.
2. Klicken Sie links in der Baumstruktur mit der linken Maustaste auf eine JavaScript-Datei.
3. Klicken Sie oben auf Edit test.
   
   Ergebnis: Die entsprechende JavaScript-Datei des Tests öffnet sich.
4. Bearbeiten Sie das Skript.
   
   Das System lädt geänderte Tests automatisch neu, wenn Sie auf Reload oder Run all tests klicken.
5. Klicken Sie oben auf Save.

Einen Test eines Workflows automatisch erzeugen

---

Sie können einen Test für einen bereits gelaufenen Workflow automatisch erzeugen, um einen Workflow auf Korrektheit zu prüfen.

Einen bereits gelaufenen Workflow über die Suche finden

1. Öffnen Sie links in der Seitenleiste Suche.
2. Suchen Sie mithilfe des Filters Alles und der Filteroption Name - freie Eingabe nach der Endung acwl.
   
   Ergebnis: Sie erhalten alle durchgelaufenen Workflows im Suchergebnis (siehe Abbildung Nach Workflows suchen).
3. Klicken Sie mit der rechten Maustaste auf einen Eintrag aus dem Suchergebnis.

Einen bereits gelaufenen Workflow über einen Anhang finden

1. Öffnen Sie links in der Seitenleiste Explorer.
2. Öffnen Sie den Pfad zum Dokument, das als Anhang von einem Workflow bearbeitet wurde.
3. Wählen Sie den Anhang aus und öffnen Sie rechts die Registerkarte Übersicht.
4. Finden Sie den gewünschten Workflow und klicken Sie ihn mit der rechten Maustaste an.

Einen Test erzeugen

1. Klicken Sie mit der rechten Maustaste auf den gefundenen Workflow.
2. Wählen Sie im Kontextmenü Development > Workflow log reader.
   
   Ergebnis:
   
   • Der Workflow log reader öffnet sich.
   • Sie sehen links in der Tabelle die Schritte des durchgelaufenen Workflows (siehe Abbildung Workflow log reader).
3. Klicken Sie oben auf Code enviroment >  Test starting the workflow directly (with an attachment).
   
   Ergebnis: Das System baut automatisch einen Test in Form eines Skripts für den durchgelaufenen Workflow auf.

   Hinweis: Das Skript enthält die JavaScript-Bibliotheken:
   
   • common/objects
   • common/beans
   • agorum.dev/js/lib/delta
   • agorum.dev/js/lib/workflow
   • agorum.dev/js/lib/assert
   • agorum.dev/js/lib/finder
   • agorum.dev/js/lib/cleaner

4. Klicken Sie oben auf Save as test.
5. Wählen Sie Ihr Konfigurationsprojekt und vergeben Sie einen Namen für das Skript.
6. Klicken Sie auf OK.
   
   Ergebnis: Das System speichert den Test im gewählten Konfigurationsprojekt unter:

   Eigene Dateien/Administration/customers/<Konfigurationsprojekt>/test/js

   Hinweise:
   
   • Das System führt den Test stets mit dem Test-Anhang test.pdf durch, wenn Sie das gespeicherte Test-Skript starten.

   • Sie müssen den Test-Anhang test.pdf sowie den Ordner pdf manuell erstellen unter:

   Eigene Dateien/Administration/customers/<Konfigurationsprojekt>/test/pdf

7. Passen Sie den erzeugten Test für den Workflow an, damit der Test lauffähig ist.

 

Metadaten eines Objekts für Tests auslesen

---

Für manche Tests benötigen Sie Metadaten, damit Sie Tests vollständig ausführen können. Die Metadaten eines Objekts können Sie über das Kontextmenü auslesen.

1. Öffnen Sie links in der Seitenleiste Explorer.
2. Klicken Sie mit der rechten Maustaste auf ein Objekt.
3. Wählen Sie im Kontextmenü Development > Metadata reader.
   
   Ergebnis:
   
   • Der Metadata reader zum gewählten Objekt öffnet sich.
   • Sie können zwischen den Modi variable und metadata save wählen.
   
   variable
   Erzeugt ein Skript mit den Metadaten des Objekts.
   
   metadata save
   • Erzeugt ein Skript mit den Metadaten eines Objekts, die das System direkt in die Variable object speichert.
   • Dient zur weiteren Verarbeitung im System, etwa für docform, um die Metadaten eines Objekts wiederherzustellen.

Aufbau eines Test-Skripts

---

/* globals describe, it, before, after, beforeEach, afterEach */

let objects = require('common/objects');
let assert = require('/agorum/roi/customers/agorum.dev/js/lib/assert');

// desribe a group of tests
describe('Test-Group', () => {
  before('before', () => {
    // is called before the first "it"
  });

  after('after', () => {
    // is called after the last "it"
    // may be used to clean up
  });

  beforeEach('before each', () => {
    // is called before each "it"
  });
  
  afterEach('after each', () => {
    // is called after each "it"
  });

  // define your first test
  it('Test 1', cx => {
    // Put in your test
    
    // wait for anything 
    let result = cx.wait('Describe, what you are waiting for').seconds(10).for(() => {
      // return what you found
      return 'anything';
    });

    // define checkpoints, that are shown as progress in the test suite
    cx.checkpoint('Checkpoint 1');
    
    // assert the result (should be "anything")
    assert('Check with isEqual').isEqual(result, 'anything');
  });

  // define your second test
  it('Test 2', () => {
    // ...
    // if the test returns anything, it is marked as failed
    // you can also throw an error to mark it as failed
  });
});

describe

Definiert eine Test-Gruppe.

• Sie können beliebige describes ineinander verschachteln.
• Das System erstellt daraus in der Testsuite eine Baumstruktur der Tests.

it

Definiert den Test an sich und führt ein oder mehrere Tests durch.

• Sie können beliebig viele it definieren.
• Unterhalb von it darf kein weiteres it oder describe vorhanden sein.
• Der Test gilt als fehlgeschlagen, wenn die Funktion ein Ergebnis zurückliefert.
• Der Test gilt als bestanden, wenn die Funktion nichts zurückliefert.
• Sie können auch ein throw new Error verwenden, damit der Test fehlschlägt.
• Ein it kann auch einen Promise zurückliefern, etwa:

it('Test mit promise', cx => {
  return new Promise(resolve => {
    // ... etwas Asynchrones tun ...
    resolve();
  });
});

// oder
it('Test mit fork', cx => { // "fork" in der Regel nicht notwendig, da die Tests automatisch in eigenen Threads laufen
  return aguila.fork(() => {
    // ... etwas Asynchrones tun ...
  });
});

describe.only

Ignoriert alle anderen normalen decribes, sofern mindestens ein describe.only (statt describe) existiert.

Das System betrachtet beim Ausführen der Tests nur noch diejenigen Gruppen, die only sind.

it.only

Ignoriert alle anderen normalen it, sofern mindestens ein it.only (statt it) existiert, und führt nur die it.only aus.

describe.skip

Ignoriert die aufgeführte Gruppe.

it.skip

Ignoriert den aufgeführten Test.

before

Wird ausgeführt vor dem ersten it innerhalb dieser Gruppe.

Verwenden Sie before, um Testdaten vorzubereiten.

after

Wird ausgeführt nach dem letzten it innerhalb dieser Gruppe.

Verwenden Sie after, um Testdaten aufzuräumen.

beforeEach

Wird vor jedem einzelnen it innerhalb dieser Gruppe ausgeführt.

afterEach

Wird nach jedem einzelnen it innerhalb dieser Gruppe ausgeführt.

cx

Stellt einen Kontext innerhalb des Tests dar und kann verwendet werden für:

• cx.checkpoint
• cx.wait

cx.checkpoint

Setzt einen Checkpoint.

• Dient dazu, um in der Testsuite anzuzeigen, wo sich der Test gerade befindet.
• Für sehr lange it sinnvoll, sodass Sie sehen, was gerade passiert.

cx.wait

Wartet auf etwas.

• Das System wartet x Sekunden darauf, dass die Funktion in for etwas zurückliefert.
• Das System wirft einen Fehler, sofern diese Funktion innerhalb der definierten Zeit nichts zurückliefert.
• wait setzt selbstständig Checkpoints und zeigt dem Benutzer in der Testsuite an, wie lange noch gewartet wird, etwa:

cx.wait('Ein sinnvoller Text, worauf hier gewartet wird').seconds(Anzahl Sekunden).for(<Funktion, die im Erfolgsfall etwas zurückliefert>);

Sie können anstatt seconds auch minutes verwenden:

Das System:

• ruft die Funktion in for jede Millisekunde auf, sofern das Zeitfenster unter 1 Sekunde ist
• ruft die Funktion in for jede Sekunde auf, sofern das Zeitfenster unter 1 Minute ist
• ruft die Funktion in for jede 10-Sekunden auf, sofern keines der beiden Zeitfenster zutrifft

Beispiel 1

Warte maximal 120 Sekunden auf das Erscheinen einer bestimmten Datei in einem Ordner und gib diese Datei zurück:

let folder = objects.find('/agorum/roi/Files/xy');
let file = cx.wait('Datei test.txt in Ordner xy enthalten?').seconds(120).for(() => {
  return folder.getItem('test.txt');
});

// mit file weiterarbeiten

Beispiel 2

Warte maximal 120 Sekunden, bis ein bestimmtes Objekt in der Suche gefunden wurde, und gib die UUID zurück:

let uuid = cx.wait('Finde Objekt mit prefix_kennung=123').seconds(120).for(() => {
  let result = objects.query('prefix_kennung:123').limit(1).search('uuid');
  if (result && result[0]) return result[0].uuid;
});

// mit der uuid weiterarbeiten

assert

Stellt eine Hilfsfunktion zur Prüfung von erwarteten Ergebnissen dar (siehe JavaScript-Bibliothek agorum.dev/js/lib/assert).

Beispiele

---

Die Ablage eines Dokuments prüfen

Überprüfen, ob eine Datei im korrekten Ordner abgelegt wurde:

assert('Ist korrekt abgelegt').isTruthy(objects.tryFind('</erwarteter Pfad/erwarteter Dateiname.Dateiendung>'));

Überprüfen, ob eine Datei im korrekten Ordner abgelegt wurde (mit Verweis auf den Objektnamen):

assert('Ist korrekt abgelegt').isTruthy(objects.tryFind('</erwarteter Pfad/'> + obj.name));