# Session

Import: `import com.install4j.api.test.session.Session;`

```java
interface Session extends AutoCloseable
```

Shared base for [`InstallerSession`](InstallerSession.md), [`UninstallerSession`](UninstallerSession.md) and
[`InstallerApplicationSession`](InstallerApplicationSession.md). 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`](../InstallerTestException.md) 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 [`Session.waitForScreenId`](Session.md#waitforscreenid-string).
- `session.onCurrentScreen { ... }`— wraps [`Session.currentScreen`](Session.md#currentscreen).
- `session.onDialog(predicate) { ... }`— wraps [`Session.dialog`](Session.md#dialog-dialogmatcher).
- `session.onAlert { ... }`— wraps [`Session.alert`](Session.md#alert).
- `session.onFileChooser { ... }`— wraps [`Session.fileChooser`](Session.md#filechooser).
- `session.onLanguageDialog { ... }`— wraps [`Session.languageDialog`](Session.md#languagedialog).
- `session.onRunningProcessesDialog { ... }`— wraps
[`Session.runningProcessesDialog`](Session.md#runningprocessesdialog).
- `session.onCreateUserDialog { ... }`— wraps [`Session.createUserDialog`](Session.md#createuserdialog).
- `session.onPasswordDialog { ... }`— wraps [`Session.passwordDialog`](Session.md#passworddialog).
- `session["varName"]`— operator form of [`Session.getVariable`](Session.md#getvariable-string).

Example:

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

## Methods

| Signature | Returns | Description |
|---|---|---|
| [`currentScreen()`](#currentscreen) | `ScreenHandle` | The currently active wizard screen. |
| [`currentScreen(Duration)`](#currentscreen-duration) | `ScreenHandle` | Same as [`Session.currentScreen`](Session.md#currentscreen) with an explicit timeout. |
| [`dialog(DialogMatcher)`](#dialog-dialogmatcher) | `DialogHandle` | Wait for a modal dialog whose backing window matches the given [`DialogMatcher`](../ui/DialogMatcher.md). |
| [`dialog(DialogMatcher, Duration)`](#dialog-dialogmatcher-duration) | `DialogHandle` | Same as [`Session.dialog`](Session.md#dialog-dialogmatcher) with an explicit timeout. |
| [`alert()`](#alert) | `AlertHandle` | Wait for a JOptionPane-built alert. |
| [`alert(Duration)`](#alert-duration) | `AlertHandle` | Same as [`Session.alert`](Session.md#alert) with an explicit timeout. |
| [`fileChooser()`](#filechooser) | `FileChooserHandle` | Wait for the modal JFileChooser dialog shown by a Browse button. |
| [`fileChooser(Duration)`](#filechooser-duration) | `FileChooserHandle` | Same as [`Session.fileChooser`](Session.md#filechooser) with an explicit timeout. |
| [`languageDialog()`](#languagedialog) | `LanguageSelectionDialogHandle` | Wait for the startup language-selection dialog. |
| [`languageDialog(Duration)`](#languagedialog-duration) | `LanguageSelectionDialogHandle` | Same as [`Session.languageDialog`](Session.md#languagedialog) with an explicit timeout. |
| [`runningProcessesDialog()`](#runningprocessesdialog) | `RunningProcessesDialogHandle` | Wait for the running-processes dialog shown by a "Check for running processes" action. |
| [`runningProcessesDialog(Duration)`](#runningprocessesdialog-duration) | `RunningProcessesDialogHandle` | Same as [`Session.runningProcessesDialog`](Session.md#runningprocessesdialog) with an explicit timeout. |
| [`createUserDialog()`](#createuserdialog) | `CreateUserDialogHandle` | Wait for the create-user dialog shown by the "Create User..." button of a "Windows user selector" form component. |
| [`createUserDialog(Duration)`](#createuserdialog-duration) | `CreateUserDialogHandle` | Same as [`Session.createUserDialog`](Session.md#createuserdialog) with an explicit timeout. |
| [`passwordDialog()`](#passworddialog) | `PasswordDialogHandle` | Wait for the credentials prompt of a password dialog. |
| [`passwordDialog(Duration)`](#passworddialog-duration) | `PasswordDialogHandle` | Same as [`Session.passwordDialog`](Session.md#passworddialog) with an explicit timeout. |
| [`waitForScreenId(String)`](#waitforscreenid-string) | `ScreenHandle` | Wait until the screen with the given id becomes the active screen. |
| [`waitForScreenId(String, Duration)`](#waitforscreenid-string-duration) | `ScreenHandle` | Same as [`Session.waitForScreenId`](Session.md#waitforscreenid-string) with an explicit timeout. |
| [`waitForScreenChange()`](#waitforscreenchange) | `ScreenHandle` | Wait until the active screen changes. |
| [`waitForScreenChange(Duration)`](#waitforscreenchange-duration) | `ScreenHandle` | Same as [`Session.waitForScreenChange`](Session.md#waitforscreenchange) with an explicit timeout. |
| [`navigateUntilScreen(String, int)`](#navigateuntilscreen-string-int) | `void` | Advance the wizard until the screen with the given id is the active screen. |
| [`navigateUntil(int, Predicate<String>)`](#navigateuntil-int-predicate-string) | `void` | Advance the wizard one screen at a time until the given predicate matches the current screen id. |
| [`getLanguageId()`](#getlanguageid) | `String` | The current installer language id, e.g. |
| [`getInstallationDirectory()`](#getinstallationdirectory) | `File` | The active installation directory. |
| [`getVariable(String)`](#getvariable-string) | `Object` | Returns the installer variable with the given name, or `null` if no variable with that name is set on the installer context. |
| [`getLogFile()`](#getlogfile) | `File` | The installer log file being captured by this session. |
| [`readLog()`](#readlog) | `String` | Read the entire installer log as a string. |
| [`awaitExit()`](#awaitexit) | `int` | Block until the installer-application thread exits and return its exit code. |
| [`awaitExit(Duration)`](#awaitexit-duration) | `int` | Same as [`Session.awaitExit`](Session.md#awaitexit) with an explicit timeout. |
| [`isFinished()`](#isfinished) | `boolean` | Whether the installer-application thread has exited. |
| [`terminate()`](#terminate) | `void` | Force a shutdown by interrupting the installer thread and tearing down. |
| [`close()`](#close) | `void` | Calls [`Session.terminate`](Session.md#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. |

### currentScreen()

```java
ScreenHandle currentScreen()
```

The currently active wizard screen.

### currentScreen(Duration)

```java
ScreenHandle currentScreen(Duration timeout)
```

Same as [`Session.currentScreen`](Session.md#currentscreen) with an explicit timeout.

### dialog(DialogMatcher)

```java
DialogHandle dialog(DialogMatcher matcher)
```

Wait for a modal dialog whose backing window matches the given [`DialogMatcher`](../ui/DialogMatcher.md). The
matcher sees every `javax.swing.JDialog` and any non-wizard `javax.swing.JFrame`
currently shown. Use [`DialogMatcher.any`](../ui/DialogMatcher.md#any) to accept the first dialog of any kind.

### dialog(DialogMatcher, Duration)

```java
DialogHandle dialog(DialogMatcher matcher, Duration timeout)
```

Same as [`Session.dialog`](Session.md#dialog-dialogmatcher) with an explicit timeout.

### alert()

```java
AlertHandle alert()
```

Wait for a JOptionPane-built alert.

### alert(Duration)

```java
AlertHandle alert(Duration timeout)
```

Same as [`Session.alert`](Session.md#alert) with an explicit timeout.

### fileChooser()

```java
FileChooserHandle fileChooser()
```

Wait for the modal JFileChooser dialog shown by a Browse button.

### fileChooser(Duration)

```java
FileChooserHandle fileChooser(Duration timeout)
```

Same as [`Session.fileChooser`](Session.md#filechooser) with an explicit timeout.

### languageDialog()

```java
LanguageSelectionDialogHandle languageDialog()
```

Wait for the startup language-selection dialog.

### languageDialog(Duration)

```java
LanguageSelectionDialogHandle languageDialog(Duration timeout)
```

Same as [`Session.languageDialog`](Session.md#languagedialog) with an explicit timeout.

### runningProcessesDialog()

```java
RunningProcessesDialogHandle runningProcessesDialog()
```

Wait for the running-processes dialog shown by a "Check for running processes" action.

### runningProcessesDialog(Duration)

```java
RunningProcessesDialogHandle runningProcessesDialog(Duration timeout)
```

Same as [`Session.runningProcessesDialog`](Session.md#runningprocessesdialog) with an explicit timeout.

### createUserDialog()

```java
CreateUserDialogHandle createUserDialog()
```

Wait for the create-user dialog shown by the "Create User..." button of a "Windows user
selector" form component.

### createUserDialog(Duration)

```java
CreateUserDialogHandle createUserDialog(Duration timeout)
```

Same as [`Session.createUserDialog`](Session.md#createuserdialog) with an explicit timeout.

### passwordDialog()

```java
PasswordDialogHandle passwordDialog()
```

Wait for the credentials prompt of a password dialog.

### passwordDialog(Duration)

```java
PasswordDialogHandle passwordDialog(Duration timeout)
```

Same as [`Session.passwordDialog`](Session.md#passworddialog) with an explicit timeout.

### waitForScreenId(String)

```java
ScreenHandle waitForScreenId(String id)
```

Wait until the screen with the given id becomes the active screen.

### waitForScreenId(String, Duration)

```java
ScreenHandle waitForScreenId(String id, Duration timeout)
```

Same as [`Session.waitForScreenId`](Session.md#waitforscreenid-string) with an explicit timeout.

### waitForScreenChange()

```java
ScreenHandle waitForScreenChange()
```

Wait until the active screen changes.

### waitForScreenChange(Duration)

```java
ScreenHandle waitForScreenChange(Duration timeout)
```

Same as [`Session.waitForScreenChange`](Session.md#waitforscreenchange) with an explicit timeout.

### navigateUntilScreen(String, int)

```java
default void navigateUntilScreen(String terminalScreenId, int maxHops)
```

Advance the wizard until the screen with the given id is the active screen. Same as
[`Session.navigateUntil`](Session.md#navigateuntil-int-predicate-string) for the common case of advancing to a specific id.

### navigateUntil(int, Predicate<String>)

```java
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. Returns silently if the installer-application thread finishes while navigating.

### getLanguageId()

```java
String getLanguageId()
```

The current installer language id, e.g. `"en"`, `"de"`.

### getInstallationDirectory()

```java
File getInstallationDirectory()
```

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

### getVariable(String)

```java
@Nullable 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. The value must be `java.io.Serializable`
in subprocess mode.

### getLogFile()

```java
File getLogFile()
```

The installer log file being captured by this session.

### readLog()

```java
String readLog()
```

Read the entire installer log as a string.

### awaitExit()

```java
int awaitExit()
```

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

### awaitExit(Duration)

```java
int awaitExit(Duration timeout)
```

Same as [`Session.awaitExit`](Session.md#awaitexit) with an explicit timeout.

### isFinished()

```java
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
[`Session.currentScreen`](Session.md#currentscreen) no longer work because the wizard frame has been disposed.

### terminate()

```java
void terminate()
```

Force a shutdown by interrupting the installer thread and tearing down. Always succeeds.

### close()

```java
void close()
```

Calls [`Session.terminate`](Session.md#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.

