# 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.1</version>
  <scope>test</scope>
</dependency>
```

**Gradle**:

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

Getting started

A UI test against an install4j installer follows three steps:
- 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).
- Open an [`InstallerSession`](session/InstallerSession.md) via
[`InstallerSessionBuilder.forMediaFile`](session/InstallerSessionBuilder.md#formediafile-file), or an
[`UninstallerSession`](session/UninstallerSession.md) /
[`InstallerApplicationSession`](session/InstallerApplicationSession.md) from a previously
installed directory.
- Drive the wizard with [`Session.currentScreen`](session/Session.md#currentscreen) and
[`ScreenHandle`](ui/ScreenHandle.md) 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`](session/UninstallerSession.md) and
[`InstallerApplicationSession`](session/InstallerApplicationSession.md) 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`](InstallerTestException.md) 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.

## Types

| Type | Kind | Description |
|---|---|---|
| [InstallerTestException](InstallerTestException.md) | class | Base unchecked exception for all failures originating from the install4j testing API. |

