Testing Electron applications

Version 5.2.0

18

4.5+

Electron is a framework for executing cross-platform desktop applications using the web browser Chromium and the Node.js framework. HTML, CSS und JavaScript can be used for the development of the applications. Electron applications can access native functionality of the operating system such as menus, files or the task bar.

Since version 4.5 QF-Test can handle applications developed via the Electron framework. All features QF-Test supports for the web engine can also be used for Electron testing.

18.1

Starting the Electron Client

Connecting to an Electron application is quite similiar to connecting to a web application (connection mode 'WebDriver', see subsection 46.3.2)

The quickstart wizard (see chapter 3) helps you generate the correct 'Setup' sequence for an easy start of the application.

The Electron specific parameters for the quickstart wizard will be explained in this chapter. For the remaining optional parameters you will find an explanation within the quickstart wizard itself.

18.1.1

Electron settings for the quickstart wizard

In the quickstart wizard select An Electron application in the section 'Type of the Application'.

Please enter the fully qualified executable for the application in the section 'Electron application'. You can make use of the file selection dialog by clicking the button to the right of the text field. If your application requires specific command line arguments, you can provide them here.

In the section 'ChromeDriver' you can either enter the respective Electron version directly or let QF-Test determine it via the button 'Detect Electron version'.

Electron is based on Node.js, which is executed in the JavaScript runtime environment 'V8'. This can be accessed via the ChromeDriver. Electron can be run on various Node versions, each of which requires a different ChromeDriver When the required ChromeDriver has already been installed QF-Test will indicate this in the bottom text field. In case it is empty, please download the ChromeDriver by clicking the button 'Download ChromeDriver'. It will be saved in the subdirectory chromedriver of the QF-Test installation directory.

18.2

Electron specific functionality of QF-Test

For Electron testing you can use all the features QF-Test offers for web testing plus the following:

18.2.1

Native Menus

The 'Selection' node allows you to control native menus in Electron applications.

Please enter the 'QF-Test ID' of the node Web page of the SUT in the attribute 'QF-Test component ID'.

The menu item to be selected goes in the 'Detail' attribute using the following syntax: clickmenu:/@<menu path>, where <menu path> is the menu name plus the menu item(s), separated by /. For example, if you want to select the menu item Save as in the menu File the correct entry would be clickmenu:@/File/Save as....

18.2.2

Native Dialogs

5.1.0+ QF-Test supports capture, check and control of dialogs instantiated with the dialog-module of Electron. For technical reasons, during the test the dialogs can be optically different from the usual Electron-dialogs.

A capture of a native dialog results in a component-node with the class Dialog. It is possible to check the text of the dialog-window using a node 'Check text'. The interaction with the dialog-window can be performed using a node 'Selection'. The 'Detail' value of a 'Selection'-node depends on a type of the dialog:

Message Box: The value of the 'Detail' attribute is the number of the button to select, e.g. 2. If the Message Box contains a CheckBox, it is possible to append its value separated with :, e.g. 2:true.
Error Box: An Error Box contains just one button, so the value of the 'Detail' attribute should be 0.
Open File Dialog: The 'Detail' attribute should contain the name of the file to select. In order to select multiple files, the 'Detail'-attribute should be set to a Json-Array containing their names, e.g. ["datei.txt","C:\\TEMP\\andere.txt"]. It is possible to cancel the dialog by setting the 'Detail'-attribute to <CANCEL>.
Save File Dialog: A Save File Dialog can be controlled in the same way as an Open File Dialog. Selection of multiple files in a Save File Dialog is not supported by Electron.

18.3

Technical remarks on testing Electron applications

To support testing the Electron APIs, i.e. record and replay native menu interaction, QF-Test has to be able to access the core Electron APIs from the renderer processes of your application. In practice, this means that the nodeIntegration preference of the BrowserWindow should not be set to false. In addition, contextIsolation must be left deactivated and enableRemoteModule must remain true:

 mainWindow = new BrowserWindow({
    webPreferences: {
        nodeIntegration: true,
        enableRemoteModule: true,
        contextIsolation: false,
        ...
    },
    ...
  })

Example 18.1: Basic example for good testability in Electron apps

If you want to avoid to expose the complete node integration into the browser window web content, you can enable QF-Test to access the API integration using a preload script:

  mainWindow = new BrowserWindow({
    webPreferences: {
        nodeIntegration: false,
        ...
        preload: `${__dirname}/preload.js` // absolute pathname required
    },
    ...
  })

Example 18.2: The require preferences for limited node integration

  // Expose require API in test mode:
  if (process.env.NODE_ENV === 'test') {
    window.electronRequire = require;
  }

Example 18.3: The corresponding preload.js

Since QF-Test always sets the NODE_ENV environment variable to test, you can use this to dynamically loosen the access security during test:

  const inTestMode = (process.env.NODE_ENV === 'test');
  mainWindow = new BrowserWindow({
    webPreferences: {
        nodeIntegration: inTestMode,
        enableRemoteModule: inTestMode,
        contextIsolation: ! inTestMode,
        ...
    },
    ...
  })

Example 18.4: Dynamic example for good testability in Electron apps

Manual