Durchsuchbare Dokumentation aufrufen | Zurück zur Dokumentationsübersicht

Navigation: Dokumentationen agorum core > agorum core für Entwickler

Tests für eigene Plugins 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
Metadaten mit dem Metadata Reader auslesen
Objekteigenschaften ermitteln und kopieren

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

Öffnen Sie links in der Seitenleiste Explorer.

Öffnen Sie Ihr Konfigurationsprojekt unter:

Eigene Dateien/Administration/customers/<Konfigurationsprojekt>

Klicken Sie das Konfigurationsprojekt mit der rechten Maustaste an.
Wählen Sie im Kontextmenü Development > Create a test from template.

Ergebnis: Der Dialog Create test script öffnet sich.
Vergeben Sie einen Namen für Ihr Skript.
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
```
Passen Sie das Skript an (siehe Aufbau eines Test-Skripts).
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.

Klicken Sie oben rechts in der Kopfleiste auf und dann auf Development > Create a test from template
Wählen Sie Ihr Konfigurationsprojekt und vergeben Sie einen Namen für Ihr Skript.
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
```
Passen Sie das Skript an (siehe Aufbau eines Test-Skripts).
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.

Öffnen Sie links in der Seitenleiste Explorer.

Öffnen Sie Ihr Konfigurationsprojekt unter:

Eigene Dateien/Administration/customers/<Konfigurationsprojekt>

Klicken Sie das Konfigurationsprojekt mit der rechten Maustaste an.
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.
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.

Öffnen Sie die Testsuite.
Klicken Sie links in der Baumstruktur mit der linken Maustaste auf eine JavaScript-Datei.
Klicken Sie oben auf Edit test.

Ergebnis: Die entsprechende JavaScript-Datei des Tests öffnet sich.
Bearbeiten Sie das Skript.

Das System lädt geänderte Tests automatisch neu, wenn Sie auf Reload oder Run all tests klicken.
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

Öffnen Sie links in der Seitenleiste Suche.
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).
Klicken Sie mit der rechten Maustaste auf einen Eintrag aus dem Suchergebnis.

Einen bereits gelaufenen Workflow über einen Anhang finden

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

Einen Test erzeugen

Klicken Sie mit der rechten Maustaste auf den gefundenen Workflow.
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).
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
Klicken Sie oben auf Save as test.
Wählen Sie Ihr Konfigurationsprojekt und vergeben Sie einen Namen für das Skript.
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
```
Passen Sie den erzeugten Test für den Workflow an, damit der Test lauffähig ist.

Nach Workflows suchen

Workflow log reader

Metadaten eines Objekts mit dem Metadata Reader 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.

Metadata Reader öffnen

Öffnen Sie links in der Seitenleiste Explorer.
Klicken Sie mit der rechten Maustaste auf ein Objekt.
Wählen Sie im Kontextmenü Development > Metadata reader.

Ergebnis: Der Metadata reader zum gewählten Objekt öffnet sich.

Metadaten-Auswahl festlegen

Sie können über die Auswahlliste What festlegen, welche Metadaten angezeigt werden sollen:

Option	Beschreibung
not inherited	Zeigt nur die nicht vererbten/vererbbaren Metadaten an (Marker `~`). Diese Metadaten sind direkt am Objekt gespeichert und werden nicht an untergeordnete Objekte vererbt.
own	Zeigt alle 'eigenen' Metadaten an (Marker `~` und `~~`). Dazu gehören sowohl nicht vererbbare Metadaten als auch Metadaten, die das Objekt an untergeordnete Objekte vererbt.
all	Zeigt alle Metadaten an, einschließlich geerbter Metadaten von übergeordneten Objekten.

Metadaten kopieren und verwenden

Der Metadata Reader bietet zwei Möglichkeiten, die angezeigten Metadaten zu kopieren:

Copy data

Kopiert nur die Metadaten-Daten als JavaScript-Objekt in die Zwischenablage.

Beispiel:

{
  ag_identifier: "test-ordner",
  ag_area: ["Kunden", "Projekte"],
  custom_field: "Wert"
}

Diese Option eignet sich, wenn Sie die Daten direkt in Ihrem Code verwenden möchten.

Copy code

Kopiert die Metadaten als vollständige JavaScript-Variable-Deklaration in die Zwischenablage.

Beispiel:

let data = {
  ag_identifier: "test-ordner",
  ag_area: ["Kunden", "Projekte"],
  custom_field: "Wert"
};

Diese Option eignet sich besonders für Test-Skripte, da die Variable direkt verwendet werden kann.

Verwendung in Tests

Die kopierten Metadaten können Sie in Test-Skripten verwenden, um:

Metadaten eines Objekts zu prüfen
Metadaten auf ein Test-Objekt zu übertragen
erwartete Metadatenwerte in Assertions zu vergleichen

Eigenschaften eines Objekts ermitteln und kopieren

Der Dialog Objekteigenschaften kopieren zeigt wichtige technische Informationen zu einem ausgewählten agorum core-Objekt an und ermöglicht das einfache Kopieren dieser Werte in die Zwischenablage.

Dialog öffnen

Öffnen Sie links in der Seitenleiste Explorer.
Klicken Sie mit der rechten Maustaste auf ein Objekt.
Wählen Sie im Kontextmenü Development > Objekteigenschaften kopieren.

Ergebnis: Das Fenster Objekteigenschaften kopieren öffnet sich.

Objekteigenschaften kopieren

Angezeigte Objekteigenschaften

Der Dialog zeigt, abhängig vom gewählten Objekt, verschiedene Objekteigenschaften an:

Eigenschaft	Beschreibung
Name	Der vollständige Name des Objekts, einschließlich Dateiendung (falls vorhanden).
UUID	Die eindeutige UUID (Universally Unique Identifier) des Objekts. Diese ändert sich nie und identifiziert das Objekt eindeutig.
ID	Die numerische interne ID des Objekts. Diese ist eindeutig innerhalb einer agorum core Instanz.
Paths	Alle Ordnerpfade, unter denen das Objekt zu finden ist. Dies umfasst sowohl den Hauptablageort als auch alle Verknüpfungen (Links). Sortierung: Die Pfade werden aufsteigend nach Länge sortiert angezeigt (kürzeste zuerst).
MetaDB	Alle MetaDB-Pfade, die mit dem Objekt verknüpft sind. Das System zeigt sowohl direkte MetaDB-Pfade als auch Pfade, die über Gruppen-Hierarchien entstehen. Was wird angezeigt: Alle MetaDB-Entries und Bundles im Pfad des Objekts Optional: MetaDB-Gruppen in der Hierarchie Sowohl direkte als auch verlinkte MetaDB-Strukturen Sortierung: Die MetaDB-Pfade werden aufsteigend nach Länge sortiert angezeigt (kürzeste zuerst).
Require	Fertige `require()`-Statements für JavaScript-Dateien. Diese Kategorie wird nur angezeigt, wenn das Objekt eine JavaScript-Datei ist oder ein `index.js` enthält. Eigenschaften: Automatische Variablennamen-Generierung aus dem Dateinamen (camelCase) Entfernung der `.js`-Endung Sortierung nach Pfadlänge (aufsteigend)

Werte kopieren

Neben jedem Wert befindet sich ein Kopieren-Symbol .

Klicken Sie auf das Kopieren-Symbol neben dem gewünschten Wert.

Ergebnis:
• Der Wert wird in die Zwischenablage kopiert
• Das Symbol ändert sich kurzzeitig zu einem Häkchen ✔, um die erfolgreiche Aktion zu bestätigen
Fügen Sie den kopierten Wert an der gewünschten Stelle ein (etwa in einem Test-Skript).

Aufbau eines Test-Skripts

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

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

// desribe a group of tests
describe('test group', () => {
  /** @type {agorum.FolderObject} */
  let resources;
  /** @type {agorum.FolderObject} */
  let workspace;
  /** @type {cleaner.Cleaner} */
  let c;

  before('before', () => {
    // look up this test's resources and workspace folders
    let pkg = beans.up(objects.find(module.id), '[~identifier=ag_package]');

    resources = pkg.getItem('test');
    workspace = objects.find('agorum/roi/workspace').createPath(pkg.name + '/test');
    c = cleaner();
  });

  after('after', () => {
    // clean up created objects
    c.clean();
  });

  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.

Beispiel:

  before('before', () => {
    // is called before the first "it"
  });

after

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

Verwenden Sie after, um Testdaten aufzuräumen.

Beispiel:

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

beforeEach

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

Beispiel:

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

afterEach

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

Beispiel:

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

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

Hinweis: Sobald der return-Wert einer truthy-Antwort (NICHT: undefined, false, '') entspricht, wird der wait abgebrochen und das Ergebnis weitergeleitet.

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).

aguila-Widgets testen

Automatisierte Tests für aguila-Widgets erfordern einen besonderen Umgang, da Autotests außerhalb des aguila-UI-Threads laufen, Widget-Zugriffe aber nur innerhalb des UI-Threads erlaubt sind. Die Funktion aguila.invoke() löst dieses Problem: Sie führt eine Funktion synchron im UI-Thread aus und gibt den Rückgabewert zurück.

Voraussetzungen

Für Widget-Tests werden folgende Imports benötigt:

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

Widget im Test laden

Laden Sie das zu testende Widget mit require.exec() innerhalb von aguila.invoke().

Tipp: Testen Sie immer das echte Widget – bauen Sie den Widget-Code nicht im Test nach.

let testForm;

before('setup', () => {
  testForm = aguila.invoke(() => {
    // Das echte Widget laden – NICHT den Code im Test duplizieren!
    let w = require.exec(
      objects.find(require.resolve('/agorum/roi/customers/<Konfigurationsprojekt>/js/aguila/<widget-name>'))
    );
    w.popup({});
    return w;
  });
});

after('cleanup', () => {
  aguila.invoke(() => {
    testForm && testForm.form && testForm.form.close && testForm.form.close();
  });
});

Hinweis: require.exec() ist die bevorzugte Methode für Tests, da sie keine Widget-Registrierung erfordert. Der Aufruf muss innerhalb von invoke() erfolgen.

Widget-Werte lesen und setzen

Jeder Widget-Zugriff (lesen, schreiben, Events auslösen) muss in einem eigenen aguila.invoke()-Block stattfinden:

it('should have correct value', () => {
  // Wert setzen
  aguila.invoke(() => {
    testForm.set('fieldName.value', 42);
  });

  // Wert lesen und prüfen
  let result = aguila.invoke(() => {
    return testForm.get('fieldName.value');
  });

  assert('Wert sollte 42 sein').isEqual(42, result);
});

Benutzereingaben simulieren

Verwenden Sie fire('input', ...), um echte Benutzereingaben zu simulieren. Das ist besser als nur Werte zu setzen, da so der gleiche Code-Pfad wie bei einer echten Benutzereingabe durchlaufen wird:

it('should react to user input', () => {
  aguila.invoke(() => {
    // Erst Werte setzen
    testForm.set('celsius.value', 100);
    // Dann input-Event feuern, um die Berechnung auszulösen
    testForm.fire('input', { name: 'celsius', value: 100, oldValue: 0 });
  });

  let result = aguila.invoke(() => {
    return testForm.get('fahrenheit.value');
  });

  assert('100°C sollten 212°F sein').isEqual(212, result);
});

Prüfen, ob Felder existieren

it('should have all required fields', () => {
  let fields = aguila.invoke(() => {
    return [
      testForm.down('meters') !== null && testForm.down('meters') !== undefined,
      testForm.down('kilometers') !== null && testForm.down('kilometers') !== undefined,
    ];
  });

  assert('meters field should exist').isTrue(fields[0]);
  assert('kilometers field should exist').isTrue(fields[1]);
});

Best Practice: Lib-Tests und UI-Tests trennen

Trennen Sie Geschäftslogik von der Oberfläche und testen Sie beides separat:

Testtyp	Was wird getestet
Lib-Test	Reine Logik (Berechnungen, Konvertierungen) ohne aguila
UI-Test	Widget-Verhalten, Benutzerinteraktion mit aguila.invoke(), testet die Oberfläche

Fehler in der Berechnungslogik werden auf diese Weise sofort gefunden, ohne dass die Widget-Erzeugung funktionieren muss. Die UI-Tests prüfen dann nur noch, ob die Oberfläche die Bibliothek korrekt einbindet.

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));

Autotests für E-Mails

Siehe E-Mail-Autotests

Beispiel für einen UI-Test (mit aguila)

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

describe('distance converter UI tests', () => {
  let testForm;

  before('setup', () => {
    testForm = aguila.invoke(() => {
      let w = require.exec(
        objects.find(require.resolve('/agorum/roi/customers/<Konfigurationsprojekt>/js/aguila/<example>'))
      );
      w.popup({});
      return w;
    });
  });

  after('cleanup', () => {
    aguila.invoke(() => {
      testForm && testForm.form && testForm.form.close && testForm.form.close();
    });
  });

  it('should update all fields when user enters 1000 meters', () => {
    aguila.invoke(() => {
      testForm.set('meters.value', 1000);
      testForm.fire('input', { name: 'meters', value: 1000, oldValue: 0 });
    });

    let km = aguila.invoke(() => {
      return testForm.get('kilometers.value');
    });

    assert('kilometers should be 1').isEqual(1, km);
  });
});

Tests automatisieren

Siehe JavaScript-Bibliothek agorum.dev/js/lib/runner