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.

Example:

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

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

    • 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