Session (install4j API)
Description: declaration: package: com.install4j.api.test.session, interface: Session

# Interface Session

All Superinterfaces:
  `AutoCloseable`

All Known Subinterfaces:
  `InstallerApplicationSession, InstallerSession, UninstallerSession`

public interface Session extends AutoCloseable
Shared base for `InstallerSession`, `UninstallerSession` and `InstallerApplicationSession`. Provides screen and dialog access log access and lifecycle.

Every wait method has a no-arg form that uses the builder-configured default timeout and a `Duration` overload. Wait methods throw a typed `InstallerTestException` subtype on timeout. They never return `null`.

## Kotlin extensions

The `SessionExtensions.kt` file in this package adds Kotlin-only convenience extensions on top of this interface. Each is a thin inline wrapper that waits for the matching screen or dialog, runs the given trailing lambda on the handle as `this`, and returns the handle.

- `session.onScreen(id) { ... }` — wraps `waitForScreenId(String)`.
- `session.onCurrentScreen { ... }` — wraps `currentScreen()`.
- `session.onDialog(predicate) { ... }` — wraps `dialog(DialogMatcher)`.
- `session.onAlert { ... }` — wraps `alert()`.
- `session.onFileChooser { ... }` — wraps `fileChooser()`.
- `session.onLanguageDialog { ... }` — wraps `languageDialog()`.
- `session.onRunningProcessesDialog { ... }` — wraps `runningProcessesDialog()`.
- `session.onCreateUserDialog { ... }` — wraps `createUserDialog()`.
- `session.onPasswordDialog { ... }` — wraps `passwordDialog()`.
- `session["varName"]` — operator form of `getVariable(String)`.

Example:

    session.onScreen("installDir") {
        directoryChooser().setDirectory(target)
        clickNext()
    }
    session.onAlert { clickYes() }
    val installedAs: String? = session["installedAs"] as String?

- ## Method Summary

  Modifier and Type
  Method
  Description
  `AlertHandle`
  `alert()`
  Wait for a JOptionPane-built alert.
  `AlertHandle`
  `alert(Duration timeout)`
  Same as `alert()` with an explicit timeout.
  `int`
  `awaitExit()`
  Block until the installer-application thread exits and return its exit code.
  `int`
  `awaitExit(Duration timeout)`
  Same as `awaitExit()` with an explicit timeout.
  `void`
  `close()`
  Calls `terminate()` if the session is still running, then deletes the extraction cache for media-file based sessions and deletes the auto-created installation directory if the session created it.
  `CreateUserDialogHandle`
  `createUserDialog()`
  Wait for the create-user dialog shown by the "Create User..." button of a "Windows user selector" form component.
  `CreateUserDialogHandle`
  `createUserDialog(Duration timeout)`
  Same as `createUserDialog()` with an explicit timeout.
  `ScreenHandle`
  `currentScreen()`
  The currently active wizard screen.
  `ScreenHandle`
  `currentScreen(Duration timeout)`
  Same as `currentScreen()` with an explicit timeout.
  `DialogHandle`
  `dialog(DialogMatcher matcher)`
  Wait for a modal dialog whose backing window matches the given `DialogMatcher`.
  `DialogHandle`
  `dialog(DialogMatcher matcher, Duration timeout)`
  Same as `dialog(DialogMatcher)` with an explicit timeout.
  `FileChooserHandle`
  `fileChooser()`
  Wait for the modal JFileChooser dialog shown by a Browse button.
  `FileChooserHandle`
  `fileChooser(Duration timeout)`
  Same as `fileChooser()` with an explicit timeout.
  `File`
  `getInstallationDirectory()`
  The active installation directory.
  `String`
  `getLanguageId()`
  The current installer language id, e.g.
  `File`
  `getLogFile()`
  The installer log file being captured by this session.
  `Object`
  `getVariable(String name)`
  Returns the installer variable with the given name, or `null` if no variable with that name is set on the installer context.
  `boolean`
  `isFinished()`
  Whether the installer-application thread has exited.
  `LanguageSelectionDialogHandle`
  `languageDialog()`
  Wait for the startup language-selection dialog.
  `LanguageSelectionDialogHandle`
  `languageDialog(Duration timeout)`
  Same as `languageDialog()` with an explicit timeout.
  `default void`
  `navigateUntil(int maxHops, Predicate<String> isTerminal)`
  Advance the wizard one screen at a time until the given predicate matches the current screen id.
  `default void`
  `navigateUntilScreen(String terminalScreenId, int maxHops)`
  Advance the wizard until the screen with the given id is the active screen.
  `PasswordDialogHandle`
  `passwordDialog()`
  Wait for the credentials prompt of a password dialog.
  `PasswordDialogHandle`
  `passwordDialog(Duration timeout)`
  Same as `passwordDialog()` with an explicit timeout.
  `String`
  `readLog()`
  Read the entire installer log as a string.
  `RunningProcessesDialogHandle`
  `runningProcessesDialog()`
  Wait for the running-processes dialog shown by a "Check for running processes" action.
  `RunningProcessesDialogHandle`
  `runningProcessesDialog(Duration timeout)`
  Same as `runningProcessesDialog()` with an explicit timeout.
  `void`
  `terminate()`
  Force a shutdown by interrupting the installer thread and tearing down.
  `ScreenHandle`
  `waitForScreenChange()`
  Wait until the active screen changes.
  `ScreenHandle`
  `waitForScreenChange(Duration timeout)`
  Same as `waitForScreenChange()` with an explicit timeout.
  `ScreenHandle`
  `waitForScreenId(String id)`
  Wait until the screen with the given id becomes the active screen.
  `ScreenHandle`
  `waitForScreenId(String id, Duration timeout)`
  Same as `waitForScreenId(String)` with an explicit timeout.

- ## Method Details

  - ### currentScreen

    @NotNull ScreenHandle currentScreen()
    The currently active wizard screen.

  - ### currentScreen

    @NotNull ScreenHandle currentScreen(@NotNull Duration timeout)
    Same as `currentScreen()` with an explicit timeout.

  - ### dialog

    @NotNull DialogHandle dialog(@NotNull DialogMatcher matcher)
    Wait for a modal dialog whose backing window matches the given `DialogMatcher`. The matcher sees every `JDialog` and any non-wizard `JFrame` currently shown. Use `DialogMatcher.any()` to accept the first dialog of any kind.

  - ### dialog

    @NotNull DialogHandle dialog(@NotNull DialogMatcher matcher, @NotNull Duration timeout)
    Same as `dialog(DialogMatcher)` with an explicit timeout.

  - ### alert

    @NotNull AlertHandle alert()
    Wait for a JOptionPane-built alert.

  - ### alert

    @NotNull AlertHandle alert(@NotNull Duration timeout)
    Same as `alert()` with an explicit timeout.

  - ### fileChooser

    @NotNull FileChooserHandle fileChooser()
    Wait for the modal JFileChooser dialog shown by a Browse button.

  - ### fileChooser

    @NotNull FileChooserHandle fileChooser(@NotNull Duration timeout)
    Same as `fileChooser()` with an explicit timeout.

  - ### languageDialog

    @NotNull LanguageSelectionDialogHandle languageDialog()
    Wait for the startup language-selection dialog.

  - ### languageDialog

    @NotNull LanguageSelectionDialogHandle languageDialog(@NotNull Duration timeout)
    Same as `languageDialog()` with an explicit timeout.

  - ### runningProcessesDialog

    @NotNull RunningProcessesDialogHandle runningProcessesDialog()
    Wait for the running-processes dialog shown by a "Check for running processes" action.

  - ### runningProcessesDialog

    @NotNull RunningProcessesDialogHandle runningProcessesDialog(@NotNull Duration timeout)
    Same as `runningProcessesDialog()` with an explicit timeout.

  - ### createUserDialog

    @NotNull CreateUserDialogHandle createUserDialog()
    Wait for the create-user dialog shown by the "Create User..." button of a "Windows user selector" form component.

  - ### createUserDialog

    @NotNull CreateUserDialogHandle createUserDialog(@NotNull Duration timeout)
    Same as `createUserDialog()` with an explicit timeout.

  - ### passwordDialog

    @NotNull PasswordDialogHandle passwordDialog()
    Wait for the credentials prompt of a password dialog.

  - ### passwordDialog

    @NotNull PasswordDialogHandle passwordDialog(@NotNull Duration timeout)
    Same as `passwordDialog()` with an explicit timeout.

  - ### waitForScreenId

    @NotNull ScreenHandle waitForScreenId(@NotNull String id)
    Wait until the screen with the given id becomes the active screen.

  - ### waitForScreenId

    @NotNull ScreenHandle waitForScreenId(@NotNull String id, @NotNull Duration timeout)
    Same as `waitForScreenId(String)` with an explicit timeout.

  - ### waitForScreenChange

    @NotNull ScreenHandle waitForScreenChange()
    Wait until the active screen changes.

  - ### waitForScreenChange

    @NotNull ScreenHandle waitForScreenChange(@NotNull Duration timeout)
    Same as `waitForScreenChange()` with an explicit timeout.

  - ### navigateUntilScreen

    default void navigateUntilScreen(@NotNull String terminalScreenId, int maxHops)
    Advance the wizard until the screen with the given id is the active screen. Same as `navigateUntil(int, Predicate)` for the common case of advancing to a specific id.

  - ### navigateUntil

    default void navigateUntil(int maxHops, @NotNull Predicate<String> isTerminal)
    Advance the wizard one screen at a time until the given predicate matches the current screen id. Returns silently if the installer-application thread finishes while navigating.

  - ### getLanguageId

    @NotNull String getLanguageId()
    The current installer language id, e.g. `"en"`, `"de"`.

  - ### getInstallationDirectory

    @NotNull File getInstallationDirectory()
    The active installation directory. May differ from the value passed to `SessionBuilder.installationDirectory(...)` if a screen let the user change it.

  - ### getVariable

    @Nullable Object getVariable(@NotNull String name)
    Returns the installer variable with the given name, or `null` if no variable with that name is set on the installer context. The value must be `Serializable` in subprocess mode.

  - ### getLogFile

    @NotNull File getLogFile()
    The installer log file being captured by this session.

  - ### readLog

    @NotNull String readLog()
    Read the entire installer log as a string.

  - ### awaitExit

    int awaitExit()
    Block until the installer-application thread exits and return its exit code. Throws `TimeoutException` if it does not exit within the builder-configured default timeout.

  - ### awaitExit

    int awaitExit(@NotNull Duration timeout)
    Same as `awaitExit()` with an explicit timeout.

  - ### isFinished

    boolean isFinished()
    Whether the installer-application thread has exited. Useful in test loops that may race with an auto-finish terminal screen. When this is `true`, navigation operations and `currentScreen()` no longer work because the wizard frame has been disposed.

  - ### terminate

    void terminate()
    Force a shutdown by interrupting the installer thread and tearing down. Always succeeds.

  - ### close

    void close()
    Calls `terminate()` if the session is still running, then deletes the extraction cache for media-file based sessions and deletes the auto-created installation directory if the session created it.
    Specified by:
      `close` in interface `AutoCloseable`