com.install4j.api.test (install4j API)
Description: declaration: package: com.install4j.api.test

# 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.2</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.

- Related Packages
  Package
  Description
  com.install4j.api
  This package contains general utility classes for the install4j API.
  com.install4j.api.test.exceptions
  Typed unchecked exceptions thrown by the test API for specific failure categories.
  com.install4j.api.test.formcomponents
  Typed handles for every form component.
  com.install4j.api.test.session
  Session builders and the `Session` interface family.
  com.install4j.api.test.ui
  Handles for wizard screens and modal dialogs.
- Exception Classes
  Class
  Description
  InstallerTestException
  Base unchecked exception for all failures originating from the install4j testing API.