# DialogMatcher

Import: `import com.install4j.api.test.ui.DialogMatcher;`

```java
public final class DialogMatcher implements Serializable
```

Predicate over modal-dialog windows, used by [`Session.dialog`](../session/Session.md#dialog-dialogmatcher) to identify
the dialog the test wants to interact with. Serializable so it can be evaluated installer-side
in subprocess mode without sending a raw `Predicate<Window>` across the wire.

Build a matcher by chaining factory and combinator methods:

```
DialogMatcher.byClassName("com.example.MyDialog").andTitleRegex("Confirm.*")
DialogMatcher.byTitle("Save changes?")
DialogMatcher.dialogClass(JDialog.class).andContainingComponentNamed("yesButton")
```

A matcher only inspects window-side state: class, title (for `JDialog`/`JFrame`),
and the names of components in the window's component tree. It does not run arbitrary code on
the window; that would be wire-hostile.

## Methods

| Signature | Returns | Description |
|---|---|---|
| [`any()`](#any) | `DialogMatcher` | A matcher that accepts any modal dialog window. |
| [`byClassName(String)`](#byclassname-string) | `DialogMatcher` | Match by the window's runtime class name (fully qualified). |
| [`dialogClass(Class<?>)`](#dialogclass-class) | `DialogMatcher` | Convenience for [`DialogMatcher.byClassName`](DialogMatcher.md#byclassname-string) from a `Class` literal. |
| [`byTitle(String)`](#bytitle-string) | `DialogMatcher` | Match by exact title (for `JDialog`/`JFrame`). |
| [`byTitleRegex(String)`](#bytitleregex-string) | `DialogMatcher` | Match by title regex. |
| [`andClassName(String)`](#andclassname-string) | `DialogMatcher` | Narrow by class name. |
| [`andTitle(String)`](#andtitle-string) | `DialogMatcher` | Narrow by exact title. |
| [`andTitleRegex(String)`](#andtitleregex-string) | `DialogMatcher` | Narrow by title regex. |
| [`andContainingComponentNamed(String)`](#andcontainingcomponentnamed-string) | `DialogMatcher` | Narrow to dialogs that contain a child component with the given Swing name. |
| [`matches(Window)`](#matches-window) | `boolean` | Whether the given currently-showing window matches every constraint on this matcher. |
| [`toString()`](#tostring) | `String` |  |

### any()

```java
public static DialogMatcher any()
```

A matcher that accepts any modal dialog window.

### byClassName(String)

```java
public static DialogMatcher byClassName(String fqClassName)
```

Match by the window's runtime class name (fully qualified).

### dialogClass(Class<?>)

```java
public static DialogMatcher dialogClass(Class<?> dialogClass)
```

Convenience for [`DialogMatcher.byClassName`](DialogMatcher.md#byclassname-string) from a `Class` literal.

### byTitle(String)

```java
public static DialogMatcher byTitle(String exactTitle)
```

Match by exact title (for `JDialog`/`JFrame`).

### byTitleRegex(String)

```java
public static DialogMatcher byTitleRegex(String regex)
```

Match by title regex. The pattern is matched against the window's title.

### andClassName(String)

```java
public DialogMatcher andClassName(String fqClassName)
```

Narrow by class name.

### andTitle(String)

```java
public DialogMatcher andTitle(String exactTitle)
```

Narrow by exact title.

### andTitleRegex(String)

```java
public DialogMatcher andTitleRegex(String regex)
```

Narrow by title regex.

### andContainingComponentNamed(String)

```java
public DialogMatcher andContainingComponentNamed(String swingName)
```

Narrow to dialogs that contain a child component with the given Swing name.

### matches(Window)

```java
public boolean matches(Window window)
```

Whether the given currently-showing window matches every constraint on this matcher.
Returns `true` when there are no constraints set (i.e. [`DialogMatcher.any`](DialogMatcher.md#any)).

### toString()

```java
public String toString()
```

