# `Plushie.Automation.Session`
[🔗](https://github.com/plushie-ui/plushie-elixir/blob/v0.7.2/lib/plushie/automation/session.ex#L1)

An automation client attached to a running Plushie app.

The script layer does not start apps itself. Start the app with
`Plushie.start_link/2` or a mix task, then attach to the running instance
or runtime process and drive it through the real runtime and bridge.

# `bridge_ref`

```elixir
@type bridge_ref() :: GenServer.server() | nil
```

# `runtime_ref`

```elixir
@type runtime_ref() :: GenServer.server()
```

# `selector`

```elixir
@type selector() ::
  String.t()
  | {:text, String.t()}
  | {:role, String.t()}
  | {:label, String.t()}
  | :focused
```

Automation selector.

Valid forms:
- `"#save"` matches a unique local widget ID
- `"#form/save"` matches an exact scoped ID
- `{:text, "Save"}` matches visible text (content, label, value, placeholder)
- `{:role, "button"}` matches an accessibility role
- `{:label, "Save"}` matches an accessibility label
- `:focused` matches the currently focused element

Bare strings without a `#` prefix are not valid selectors.
Use `{:text, "Save"}` to match by visible text content.

# `t`

```elixir
@type t() :: %Plushie.Automation.Session{bridge: bridge_ref(), runtime: runtime_ref()}
```

# `attach`

```elixir
@spec attach(opts :: keyword()) :: t()
```

Attaches to a running Plushie app.

Accepted options:
- `:instance` - Plushie instance name; resolves runtime and bridge automatically
- `:runtime` - runtime pid or registered name
- `:bridge` - bridge pid or registered name

# `await_async`

```elixir
@spec await_async(session :: t(), tag :: atom(), timeout :: non_neg_integer()) :: :ok
```

# `canvas_move`

```elixir
@spec canvas_move(
  session :: t(),
  selector :: selector(),
  x :: number(),
  y :: number(),
  opts :: keyword()
) :: :ok
```

Moves on a canvas. Options: `window:` for multi-window apps.

# `canvas_press`

```elixir
@spec canvas_press(
  session :: t(),
  selector :: selector(),
  x :: number(),
  y :: number(),
  button :: String.t(),
  opts :: keyword()
) :: :ok
```

Presses on a canvas. Options: `window:` for multi-window apps.

# `canvas_release`

```elixir
@spec canvas_release(
  session :: t(),
  selector :: selector(),
  x :: number(),
  y :: number(),
  button :: String.t(),
  opts :: keyword()
) :: :ok
```

Releases on a canvas. Options: `window:` for multi-window apps.

# `click`

```elixir
@spec click(session :: t(), selector :: selector(), opts :: keyword()) :: :ok
```

Clicks a widget. Options: `window:` for multi-window apps.

# `find`

```elixir
@spec find(session :: t(), selector :: selector(), opts :: keyword()) ::
  Plushie.Automation.Element.t() | nil
```

# `find!`

```elixir
@spec find!(session :: t(), selector :: selector(), opts :: keyword()) ::
  Plushie.Automation.Element.t()
```

# `model`

```elixir
@spec model(session :: t()) :: term()
```

# `move_to`

```elixir
@spec move_to(session :: t(), x :: number(), y :: number()) :: :ok
```

# `pane_focus_cycle`

```elixir
@spec pane_focus_cycle(session :: t(), selector :: selector(), opts :: keyword()) ::
  :ok
```

Cycles focus in a pane grid. Options: `window:` for multi-window apps.

# `paste`

```elixir
@spec paste(
  session :: t(),
  selector :: selector(),
  text :: String.t(),
  opts :: keyword()
) :: :ok
```

Pastes text into a widget. Options: `window:` for multi-window apps.

# `press`

```elixir
@spec press(session :: t(), key :: String.t()) :: :ok
```

# `register_effect_stub`

```elixir
@spec register_effect_stub(
  session :: t(),
  kind :: Plushie.Effect.kind(),
  response :: term()
) :: :ok
```

# `release`

```elixir
@spec release(session :: t(), key :: String.t()) :: :ok
```

# `screenshot`

```elixir
@spec screenshot(session :: t(), name :: String.t(), opts :: keyword()) ::
  Plushie.Automation.Screenshot.t()
```

# `scroll`

```elixir
@spec scroll(
  session :: t(),
  selector :: selector(),
  delta_x :: number(),
  delta_y :: number(),
  opts :: keyword()
) :: :ok
```

Scrolls a scrollable widget. Options: `window:` for multi-window apps.

# `select`

```elixir
@spec select(
  session :: t(),
  selector :: selector(),
  value :: term(),
  opts :: keyword()
) :: :ok
```

Selects a value from a pick list, combo box, or radio group.
Options: `window:` for multi-window apps.

# `slide`

```elixir
@spec slide(
  session :: t(),
  selector :: selector(),
  value :: number(),
  opts :: keyword()
) :: :ok
```

Slides a slider to the given value. Options: `window:` for multi-window apps.

# `sort`

```elixir
@spec sort(
  session :: t(),
  selector :: selector(),
  column :: String.t(),
  direction :: String.t(),
  opts :: keyword()
) :: :ok
```

Sorts a table column. Options: `window:` for multi-window apps.

# `submit`

```elixir
@spec submit(session :: t(), selector :: selector(), opts :: keyword()) :: :ok
```

Submits a text input. Options: `window:` for multi-window apps.

# `toggle`

```elixir
@spec toggle(
  session :: t(),
  selector :: selector(),
  value :: boolean() | nil,
  opts :: keyword()
) :: :ok
```

Toggles a checkbox or toggler. Options: `window:` for multi-window apps.

# `tree`

```elixir
@spec tree(session :: t()) :: map()
```

# `type_key`

```elixir
@spec type_key(session :: t(), key :: String.t()) :: :ok
```

# `type_text`

```elixir
@spec type_text(
  session :: t(),
  selector :: selector(),
  text :: String.t(),
  opts :: keyword()
) :: :ok
```

Types text into a text input or editor. Options: `window:` for multi-window apps.

# `unregister_effect_stub`

```elixir
@spec unregister_effect_stub(session :: t(), kind :: Plushie.Effect.kind()) :: :ok
```

---

*Consult [api-reference.md](api-reference.md) for complete listing*
