21

Testing Electron applications

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.

21.1

Starting the Electron Client

Connecting to an Electron application can be realized using the recommended CDP-Driver connection mode (see subsection 51.3.2) or the WebDriver connection mode (see subsection 51.3.3).

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.

The video shows ' Starting your Electron application via the Quickstart wizard'.

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

Electron is based on Node.js, which is executed in the JavaScript runtime environment 'V8'. Since Electron 6 and QF-Test 5.4.0 the CDP-Driver connection mode is used to control the application. Older applications require the WebDriver connection mode in combination with a ChromeDriver. In most cases, QF-Test detects the required ChromeDriver automatically and downloads it. The downloaded driver will be saved in the subdirectory chromedriver of the QF-Test installation directory.

21.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:

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

21.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. ["file.txt","C:\\TEMP\\other.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.

21.2.3

Extended Javascript-API

5.4.0+ In Electron applications separate render processes control the content view of the application windows. In addition, a so called main process, built upon the Node.js engine, executes the main application logic. To execute individual code in the context of this process, QF-Test provides the methods mainCallJS and mainEvalJS as powerfull extension of the DocumentNode-API (see subsection 54.10.2).

In the example, the "Chrome Developer Tools"" will be displayed in the current Electron window.

rc.getComponent("genericDocument").mainCallJS("_qf_window.webContents.openDevTools()")

21.3

Technical remarks on testing Electron applications in WebDriver connection mode

To support testing the Electron APIs, e.g. record and replay native menu interaction, QF-Test has to be able to access the core Electron APIs in WebDriver connection mode 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,
        ...
    },
    ...
})

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

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

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

Starting with Electron 14, the remote module is not part of the Electron API anymore, but must be explicitly included. To do so, add at development time a reference to the @electron/remote module in your package.json and initialize the module in your main.js:

// in the main process:
require('@electron/remote/main').initialize()

QF-Test automatically uses the new module if detected. More information about the module can be found it the documentation at https://github.com/electron/remote/.

When using the CDP-Driver connection mode, no specific adaptation of the Electron application is required for QF-Test.