Testen von Electron-Anwendungen

4.5+

Electron ist ein Framework zur Ausführung von Cross-Plattform Desktop-Anwendungen mit Hilfe des Webbrowsers Chromium und des Node.js-Frameworks. Diese Anwendungen können mittels HTML, CSS und JavaScript entwickelt werden und auf native Funktionen des Betriebssystems wie Menüs, Dateien oder die Taskleiste zugreifen.

Seit QF-Test Version 4.5 können Anwendungen, die mit dem Electron Framework entwickelt wurden, getestet werden. Sämtliche Features, die QF-Test für das Web bietet, können auch hier verwendet werden.

Electron Client starten

Die Verbindung zur Electron-Anwendung kann wie bei einer Web-Anwendung über den empfohlenen CDP-Driver-Verbindungsmodus (siehe Abschnitt 50.3.2) oder den WebDriver-Verbindungsmodus (siehe Abschnitt 50.3.3) erfolgen.

Mit Hilfe des Schnellstart-Assistenten (vgl. Kapitel 3) lässt sich die passende 'Vorbereitung' Sequenz erstellen. Dies ermöglicht den einfachen Start der Anwendung.

Die Electron spezifischen Angaben im Schnellstart-Assistenten werden weiter unten in diesem Kapitel erläutert. Die verbleibenden optionalen Einstellungen sind im Schnellstart-Assistenten selbst beschrieben.

Video Das Video zeigt die ' Anbindung der Electron-Anwendung via Schnellstart-Assistenten'.

Electron Einstellungen im Schnellstart-Assistenten

Wählen Sie in der Rubrik "Typ der Anwendung" des Schnellstart-Assistenten den Punkt Eine Electron-Anwendung.

Geben Sie in der Rubrik "Electron-Anwendung" Ihre Anwendung inklusive Pfad an, wobei Sie das Dateiauswahlmenü nutzen können, das über den Button rechts des Eingabefelds aktiviert werden kann. Wenn Sie beim Start der Anwendung eigene Kommandozeilenargumente benötigen, so können Sie diese hier ebenfalls angeben.

Electron basiert auf Node.js, welches in der JavaScript-Laufzeitumgebung "V8" ausgeführt wird. Ab Electron 6 und QF-Test 5.4.0 wird zum Steuern der Anwendung bevorzugt der CDP-Driver-Verbindungsmodus verwendet. Für ältere Anwendungen muss auf den WebDriver-Verbindungsmodus in Kombination mit dem ChromeDriver zurückgegriffen werden. Dabei wird in den meisten Fällen der passende ChromeDriver automatisch ermittelt und heruntergeladen. Dieser wird dann im Unterverzeichnis chromedriver des QF-Test Installationsverzeichnisses gespeichert.

Electron spezifische Funktionalität in QF-Test

Neben den Features, die QF-Test für das Web bietet, steht für Electron die nachfolgend beschriebene Funktionalität zur Verfügung.

Native Menüs

Zur Ansteuerung der nativen Menüs der Electron-Anwendung verwenden Sie bitte einen 'Auswahl' Knoten, bei dem Sie im Attribut 'QF-Test ID der Komponente' die 'QF-Test ID' des Knotens Webseite des SUT angeben.

Im Attribut 'Detail' tragen Sie den Menüpunkt mit der folgenden Syntax ein: clickmenu:@/<Menüpfad>, wobei statt <Menüpfad> das Menü mit dem oder den Untermenüpunkten, getrennt durch /, einzutragen ist. Wenn Sie zum Beispiel im Menü Datei den Unterpunkt Speichern unter aktivieren wollen, lautet der Eintrag clickmenu:@/Datei/Speichern unter.

Native Dialoge

5.1.0+ QF-Test unterstützt die Aufnahme, Prüfung und Ansteuerung von Dialogen, welche mit dem dialog-Modul von Electron aufgerufen werden. Aus technischen Gründen können sich dabei die angezeigten Dialoge optisch von den üblichen Dialogen unterscheiden.

Bei der Aufnahme wird ein Komponentenknoten mit der Klasse Dialog erstellt, auf dem mit Hilfe eines 'Check Text'-Knotens der Text des Dialogfensters geprüft werden kann. Zum Interagieren mit dem Dialogfenster wird ein 'Auswahl' Knoten verwendet, wobei die Details vom Typ des Dialogs abhängen:

  • Message Box: Der Wert im Attribut 'Detail' entspricht der Nummer des ausgewählten Buttons, z.B. 2. Enthält die Message Box zusätzlich eine CheckBox, so kann deren Wert mit : getrennt angefügt werden, also z.B. 2:true.
  • Error Box: Bei einer Error Box ist nur ein Knopf vorhanden, der Rückgabewert muss daher 0 lauten.
  • Open File Dialog: Im Attribut 'Detail' muss der Dateiname der auszuwählenden Datei angegeben werden. Ist die Auswahl mehrerer Dateien erlaubt, so kann alternativ als Attribut-Wert ein Json-Array mit Dateinamen angegeben werden, also z.B. ["datei.txt","C:\\TEMP\\andere.txt"]. Möchte man den Dialog abbrechen, gibt man als Attribut-Wert <CANCEL> an.
  • Save File Dialog: Die Attribut-Werte für Save File Dialog entsprechen denen des Open File Dialogs. Eine Mehrfachauswahl wird von Electron beim Save File Dialog nicht unterstützt.

Erweiterte Javascript-API

5.4.0+ Bei Electron sind separate Render-Prozesse für die Darstellung des Inhalts der Anwendungs-Fenster verantwortlich. Zusätzlich existiert ein Haupt-Prozess, der auf der Node.js-Engine aufsetzt und die Haupt-Anwendungslogik enthält. Für die Ausführung von eigenem Skript-Code in diesem Prozess bietet QF-Test mit den Methoden mainCallJS und mainEvalJS eine mächtige Erweiterung der DocumentNode-API (siehe Abschnitt 53.11.2) an.

 
 
Object mainCallJS(String code)
Führt den JavaScript-Code im Hauptprozess der Electron-Anwendung in einer Funktion aus.
Parameter
codeDer auszuführende Code.
RückgabewertWas immer der Code mit return explizit zurückliefert, konvertiert in einen passenden Objekttyp. Allgemeine Javascript-Objekte werden in Json-Objekte konvertiert. Die spezielle Variable _qf_window wird dabei durch das BrowserWindow-Objekt ersetzt, welches zur aktuellen DocumentNode gehört.
 
Object mainEvalJS(String script)
Evaluiert JavaScript Code im Hauptprozess der Electron-Anwendung.
Parameter
scriptDas auszuführende Skript.
RückgabewertWas immer das Skript zurückliefert, konvertiert in einen passenden Objekttyp. Allgemeine Javascript-Objekte werden in Json-Objekte konvertiert. Die spezielle Variable _qf_window wird dabei durch das BrowserWindow-Objekt ersetzt, welches zur aktuellen DocumentNode gehört.
 
 

Im Beispiel werden für das aktuell angezeigte Electron-Fenster die "Chrome Developer Tools" eingeblendet.

rc.getComponent("genericDocument").mainCallJS("_qf_window.webContents.openDevTools()")
Beispiel 20.1:  SUT-Skript zum Anzeigen der Dev Tools in einem Electron-Fenster

Technische Anmerkungen zum Testen von Electron-Anwendungen im WebDriver-Verbindungsmodus

Damit QF-Test auf die Electron-APIs zugreifen kann, zum Beispiel um Interaktionen mit nativen Menüs aufzunehmen oder abzuspielen, muss QF-Test bei der Nutzung des WebDriver-Verbindungsmodus die Electron-API über den Render-Prozess der getesteten Anwendung aufgerufen werden. Dazu sollte die nodeIntegration Property des BrowserWindow nicht auf false gesetzt werden. Zusätzlich muss contextIsolation deaktiviert bleiben und enableRemoteModule den Wert true behalten.

 mainWindow = new BrowserWindow({
    webPreferences: {
        nodeIntegration: true,
        enableRemoteModule: true,
        contextIsolation: false,
        ...
    },
    ...
  })
Beispiel 20.2:  Einfaches Beispiel für eine Electron-Anwendung, die gut getestet werden kann

Wenn Sie vermeiden wollen, dass die vollständige Node-Integration im Render-Prozess zugänglich ist, können Sie die API-Integration mit Hilfe eines preload-Skripts verfügbar machen:

  mainWindow = new BrowserWindow({
    webPreferences: {
        nodeIntegration: false,
        ...
        preload: `${__dirname}/preload.js` // absolute pathname required
    },
    ...
  })
Beispiel 20.3:  Die Einstellungen für den eingeschränkten Node Zugriff
  // Expose require API in test mode:
  if (process.env.NODE_ENV === 'test') {
    window.electronRequire = require;
  }
Beispiel 20.4:  Die zugehörige Datei preload.js

Da QF-Test die NODE_ENV-Umgebungsvariable immer mit dem Wert test belegt, können Sie hierdurch dynamisch die Zugriffssicherheit während des Tests auf die benötigten Werte herabsetzen:

  const inTestMode = (process.env.NODE_ENV === 'test');
  mainWindow = new BrowserWindow({
    webPreferences: {
        nodeIntegration: inTestMode,
        enableRemoteModule: inTestMode,
        contextIsolation: ! inTestMode,
        ...
    },
    ...
  })
Beispiel 20.5:  Dynamisches Beispiel für eine Electron-Anwendung, die gut getestet werden kann

Ab Electron 14 ist das remote Modul nicht mehr Teil des Electron-Frameworks, sondern muss explizit in die Anwendung eingebunden werden. Dazu muss beim Erstellen der Anwendung das Modul @electron/remote in der package.json referenziert und in der main.js initialisiert werden:

  // im "Main"-Prozess:
  require('@electron/remote/main').initialize()
Beispiel 20.6:  Die Initialisierung des @electron/remote Moduls

QF-Test verwendet dann für die Zugriffe auf Haupt-Prozess automatisch dieses neue Modul. Weitere Infos finden sich in der Modul-Dokumentation unter https://github.com/electron/remote/.

Bei der Nutzung des CDP-Driver-Verbindungsmodus ist keine Anpassung der Electron-Anwendung für den Test notwendig.