Package com.install4j.api.test

package com.install4j.api.test
The install4j Test API. Write automated UI tests that drive the actual UI of an installer, uninstaller, or custom installer application from inside a test JVM.

The Test API is a separately versioned artifact. It is not part of install4j-runtime and does not ship inside generated installers. Add it to your test classpath only.

Where to get it

The Test API ships in two equivalent ways:

  • Maven Central: com.install4j:install4j-test. The artifact's POM declares a transitive dependency on the matching com.install4j:install4j-runtime.
  • Bundled with install4j at resource/install4j-test.jar inside the install4j installation directory. Pair it with resource/i4jruntime.jar from the same directory.

Maven:

<dependency>
  <groupId>com.install4j</groupId>
  <artifactId>install4j-test</artifactId>
  <version>13.0</version>
  <scope>test</scope>
</dependency>

Gradle:

dependencies {
    testImplementation("com.install4j:install4j-test:...")
}

Getting started

A UI test against an install4j installer follows three steps:

  1. Build the installer media for at least one platform (the project's .exe, .sh, or .dmg file). This is typically done by the build system before the tests run (e.g. by a compile Gradle/Maven goal of the install4j plugin).
  2. Open an InstallerSession via InstallerSessionBuilder.forMediaFile(File), or an UninstallerSession / InstallerApplicationSession from a previously installed directory.
  3. Drive the wizard with Session.currentScreen() and ScreenHandle form-component accessors and assert post-conditions with assertXxx methods on the typed handles or on installer variable, log and file system state.
try (InstallerSession session = InstallerSessionBuilder
        .forMediaFile(new File("build/media/myapp-linux-x64.sh"))
        .installationDirectory(new File(tempDir, "install"))
        .start()) {
    session.waitForScreenId("welcome").nextScreen();
    session.waitForScreenId("installDir")
        .directoryChooser().setDirectory(targetDir);
    session.currentScreen().nextScreen();
    // ...
    session.awaitExit();
}

The Kotlin extensions in com.install4j.api.test.session.Sessions wrap the boilerplate in scoped lambdas (useSession { onScreen("id") { ... } }).

How the installer runs

By default the Test API launches the produced installer media as a subprocess and drives it from the test JVM over IPC. The bundled JRE, the native launcher and the actual classloader hierarchy are exercised as in a real installation. The same applies to UninstallerSession and InstallerApplicationSession where the Test API locates the matching launcher inside the installation directory.

On Linux without a usable DISPLAY, the Test API wraps the spawned installer subprocess in xvfb-run plus a reparenting window manager (metacity/mutter/openbox/fluxbox/marco) itself. Install one of those as well as xvfb-run to run UI tests on a CI machine.

In-process debug mode

SessionBuilder.debug(true) switches the session to an in-process execution where the installer runs inside the test JVM. This mode requires media built with install4jc -g (or --debug), which produces a debug_<media-name>/ directory next to the media file with the content already unpacked. The Test API throws InstallerTestException if the directory is missing. Use this mode to speed up edit-recompile-test loops or to debug the test.

JVM arguments

On JDK 24+, pass --enable-native-access=ALL-UNNAMED to silence the restricted native-access warning triggered by the native installer libraries.

Limitations

The test API handles a language selection in-process in both modes, while the normal execution will restart the installer with the correct locale set on the command line. This means that locale-specific features for a non-primary language may be different in the test modes.