> For the complete documentation index, see [llms.txt](https://docs.bugbug.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.bugbug.io/editing-tests/actions.md).

# Actions

Reference of every BugBug action step: mouse, input, window and advanced actions, with their behavior, YAML and API names, fields, special keys for Type text, capturing text from an element with Set v

An action is a test step that does something in the browser: clicks, types, navigates or runs code. The other kind of step is an [assertion](/editing-tests/assertions.md), which checks something. You can record actions or [add them manually](/editing-tests/manually-creating-the-test.md).

<figure><img src="https://3168433179-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MKixgeBPbLvnD0l1eiV%2Fuploads%2FHTnnoNv67UWK9C7RRp7B%2Fimage.png?alt=media&amp;token=6e8b54dd-c8a2-4c17-ad11-ff175146b131" alt="Step type picker in the BugBug step editor, with Actions and Assertions"><figcaption></figcaption></figure>

## All actions at a glance

The `action` name is used in [YAML](/export-import-and-backup/yaml-schema.md) files. The API and MCP use the same name as the step `type`.

| Action in the app     | `action` in YAML / API | What it does                                                  |
| --------------------- | ---------------------- | ------------------------------------------------------------- |
| Click                 | `click`                | Clicks an element.                                            |
| Double click          | `dblClick`             | Double-clicks an element.                                     |
| Right click           | `rightClick`           | Right-clicks an element to open a context menu.               |
| Hover                 | `hover`                | Moves the mouse over an element.                              |
| Move                  | `mouseMove`            | Moves the mouse to an element or to viewport coordinates.     |
| Scroll                | `scroll`               | Scrolls the window or an element.                             |
| Press mouse button    | `mouseDown`            | Presses the mouse button down (`mousedown`).                  |
| Release mouse button  | `mouseUp`              | Releases the mouse button (`mouseup`).                        |
| Drag & drop           | `dragAndDrop`          | Drags an element and drops it on another element.             |
| Type text             | `type`                 | Types text and special keys, character by character.          |
| Select option         | `select`               | Selects one or more options in a native `select`.             |
| Clear input           | `clear`                | Removes all text from a field.                                |
| Change value          | `change`               | Sets a field's value at once, without typing.                 |
| Upload file           | `uploadFile`           | Puts a file into an `<input type="file">`.                    |
| Paste from clipboard  | `pasteFromClipboard`   | Pastes the clipboard content (Ctrl+V).                        |
| Go to URL             | `goto`                 | Opens a URL in the current tab.                               |
| Go back               | `goBack`               | Goes back in the browser history.                             |
| Go forward            | `goForward`            | Goes forward in the browser history.                          |
| New tab               | `newTab`               | Opens a URL in a new tab.                                     |
| Close tab             | `closeTab`             | Closes the active tab.                                        |
| Reload page           | `reloadPage`           | Reloads the current page.                                     |
| Open inbox            | `openInbox`            | Opens a BugBug Testing Inbox mailbox.                         |
| Set variable          | `setLocalVariable`     | Saves a value, such as text from an element, for later steps. |
| Switch context        | `switchContext`        | Switches to another tab or into an iframe.                    |
| Run custom JavaScript | `execute`              | Runs your JavaScript code in the tested page.                 |
| Answer a prompt       | `answerPrompt`         | Accepts, rejects or answers `alert`, `confirm` and `prompt`.  |

## How every action works

These rules apply to all actions that target an element.

* **Selector with several matches.** If the selector matches more than one element, BugBug uses the first one. Make the [selector](/preventing-failed-tests/selectors.md) unique when you need a specific element.
* **Automatic waiting and scrolling.** Before an action runs, BugBug waits for the page and the element according to the step's [waiting conditions](/preventing-failed-tests/waiting-conditions.md), and scrolls the element into view. You rarely need a Scroll or Delay step.
* **Variables.** You can use [variables](/editing-tests/variables.md) like `{{hostname}}` in any text field of a step, including selectors and URLs.

### Fields shared by all steps

| YAML                            | API                 | Description                                                                  |
| ------------------------------- | ------------------- | ---------------------------------------------------------------------------- |
| `name`                          | `name`              | Step name shown in the test.                                                 |
| `is_active`                     | `isActive`          | `false` disables the step.                                                   |
| `notes`                         | `notes`             | Free-form notes.                                                             |
| `execution.continue_on_failure` | `continueOnFailure` | `true` lets the test continue when this step fails.                          |
| `execution.sleep`               | `sleep`             | Delay in seconds before the step runs. Empty uses the project setting.       |
| `execution.run_timeout`         | `runTimeout`        | Maximum time in seconds for the step. Empty uses the project setting.        |
| `waiting_conditions`            | `waitingConditions` | Conditions checked before the step runs. Leave them out to get the defaults. |

Element actions also take:

| YAML                   | API                   | Description                                                                                                                                                                                                                                                   |
| ---------------------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `selector`             | `selectorsPresets`    | The target element. In YAML, prefix it with `xpath=` or `css=`.                                                                                                                                                                                               |
| `interaction_position` | `interactionPosition` | Where to interact: `smart` (default), `custom`, `topLeft`, `topCenter`, `topRight`, `middleLeft`, `middleCenter`, `middleRight`, `bottomLeft`, `bottomCenter`, `bottomRight`. With `custom`, the point is given in pixels from the element's top-left corner. |

{% hint style="info" %}
YAML uses `snake_case` field names and the API and MCP use `camelCase`, for example `select_type` and `selectType`. The tables below give the YAML name.

Modifier keys on Click, Double click, Right click, Hover, Press and Release mouse button, and the secret flag on Type text and Change value, can be set in the app and in YAML, but not through the API.
{% endhint %}

YAML selectors can chain several selectors with `>>` (descendant), `<<` (ancestor) and `~` (sibling):

```yaml
selector: "xpath=//form[@id='login'] >> css=button[type='submit']"
```

## Mouse actions

### Click

`click` clicks the element matched by the selector. It also works as a tap when you [test mobile screen sizes](/workflow-tips/mobile-version-testing.md).

By default BugBug calculates the best point to click (Smart detection). You can choose another position and hold modifier keys while clicking.

<div align="left"><figure><img src="https://3168433179-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MKixgeBPbLvnD0l1eiV%2Fuploads%2FNJ8hSuAamUD69ZhPywN4%2Fimage.png?alt=media&amp;token=abb41b9d-20c2-4b10-97be-e42108bc0a99" alt="Click step parameters: Position and Modifier keys"><figcaption><p>Click parameters</p></figcaption></figure></div>

| Field                  | Description                                                         |
| ---------------------- | ------------------------------------------------------------------- |
| `selector`             | Element to click.                                                   |
| `interaction_position` | Position in the element. Default: `smart`.                          |
| `modifier_keys`        | Keys held while clicking: `ctrl`, `shift`, `alt`, `meta` (Command). |

```yaml
- action: click
  action_details:
    selector: "xpath=//button[@type='submit']"
    interaction_position: smart
```

### Double click

`dblClick` double-clicks the element, for example to open a file in a file manager. It takes the same fields as Click.

### Right click

`rightClick` right-clicks the element. Use it when your app has a custom context menu. It takes the same fields as Click.

### Hover

`hover` moves the mouse over the element. Use it for menus, previews or buttons that only appear on mouseover. It takes the same fields as Click.

{% hint style="warning" %}
Hover is not recorded automatically. [Turn on Hover mode during recording](/recording-tests-steps/recording-hover.md) to record it.
{% endhint %}

### Move

`mouseMove` moves the mouse to an element or to a point in the viewport, optionally holding mouse buttons or modifier keys. Use it for custom drag interactions or elements that react to mouse movement.

| Field                  | Description                                                                    |
| ---------------------- | ------------------------------------------------------------------------------ |
| `is_target_document`   | `false` (default) moves to the element; `true` moves to viewport coordinates.  |
| `selector`             | Target element, when `is_target_document` is `false`.                          |
| `interaction_position` | Position in the element. Default: `smart`.                                     |
| `client_x`, `client_y` | Viewport coordinates, 0 or more. Required when `is_target_document` is `true`. |
| `mouse_buttons`        | Buttons held while moving: `left`, `right`, `middle`, `back`, `forward`.       |
| `modifier_keys`        | Keys held while moving: `ctrl`, `shift`, `alt`, `meta`.                        |
| `mouse_move_steps`     | Number of intermediate move events, 1 or more.                                 |

```yaml
- action: mouseMove
  action_details:
    is_target_document: true
    client_x: 400
    client_y: 300
    mouse_buttons:
      - left
```

### Scroll

`scroll` scrolls the window or a scrollable element. You usually don't need it: BugBug [scrolls automatically](/preventing-failed-tests/smart-scroll.md) to bring an element into view before it interacts with it, including options in an open dropdown list.

Add a Scroll step when content loads only while you scroll, such as an infinite list or a dropdown that loads options dynamically. Scroll inside the list until the element from the next step is visible:

```yaml
- action: scroll
  action_details:
    scroll_inside: element
    selector: "xpath=//ul[@role='listbox']"
    scroll_to: untilNextStepElementIsVisible
```

| Field                  | Values                                                               | Description                                                        |
| ---------------------- | -------------------------------------------------------------------- | ------------------------------------------------------------------ |
| `scroll_inside`        | `window`, `element`                                                  | What to scroll. `element` needs a `selector`.                      |
| `scroll_to`            | `coords`, `edge`, `untilNextStepElementIsVisible`, `elementIntoView` | Where to scroll. `elementIntoView` needs `scroll_inside: element`. |
| `scroll_x`, `scroll_y` | number                                                               | Coordinates, with `scroll_to: coords`.                             |
| `scroll_edge`          | `topLeft` … `bottomRight`                                            | Edge to scroll to, with `scroll_to: edge`.                         |
| `scroll_direction`     | `down`, `up`, `right`, `left`                                        | Scroll direction.                                                  |

### Press mouse button and Release mouse button

`mouseDown` fires a `mousedown` event on the element, and `mouseUp` fires `mouseup`. Both take the same fields as Click.

When Drag & drop doesn't work with your app's drag implementation, combine **Press mouse button**, **Move** with the left button held (`mouse_buttons: [left]`) and **Release mouse button**. See [Recording drag & drop](/recording-tests-steps/recording-drag-and-drop.md#when-drag-and-drop-doesnt-work-with-your-app).

### Drag & drop (BETA)

`dragAndDrop` presses the mouse button on an element, moves the mouse to another element and releases it there. Use it for sortable lists, boards and custom sliders. It's [recorded automatically](/recording-tests-steps/recording-drag-and-drop.md).

| Field                           | Description                                                                                                       |
| ------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| `selector`                      | Element to drag.                                                                                                  |
| `interaction_position`          | Where to press on the dragged element. Default: `smart`.                                                          |
| `dnd_drag_x`, `dnd_drag_y`      | With `interaction_position: custom`, the press point in pixels from the dragged element's top-left corner.        |
| `drop_selector`                 | Element to drop on. In the API: `dndDropSelectorsPresets`.                                                        |
| `dnd_drop_interaction_position` | Where to release on the drop target. Same values as `interaction_position`.                                       |
| `dnd_drop_x`, `dnd_drop_y`      | With `dnd_drop_interaction_position: custom`, the release point in pixels from the drop target's top-left corner. |
| `dnd_drag_on`, `dnd_drop_on`    | Set both to `element`.                                                                                            |

```yaml
- action: dragAndDrop
  action_details:
    selector: "xpath=//*[@data-testid='card-1']"
    drop_selector: "xpath=//*[@data-testid='done-column']"
    dnd_drag_on: element
    dnd_drop_on: element
```

## Input actions

### Type text

`type` types text into an `input`, `textarea` or `contenteditable` element one character at a time, like a user on a keyboard.

* **It doesn't clear the field first.** The text is added to what the field already contains. Add a [Clear input](#clear-input) step before it.
* **It ignores `maxlength`.** The whole value is typed even if it's longer than the field's `maxlength` attribute.
* **It can press special keys.** Put a key sequence from the table below anywhere in the text, for example `hello{enter}`.
* **Keys are pressed one at a time.** Each key is pressed and released before the next one, so `{shift}`, `{ctrl}`, `{alt}` and `{command}` don't hold the key down for the next character. Key combinations such as Ctrl+A are not possible with Type text.
* **The keys must reach the step's element.** If focus moves to another element in the middle of the value, for example after `{tab}`, the step fails with `EVENT_DISPATCHED_ON_INVALID_ELEMENT`. Put `{tab}` at the end of the value.

| Key            | Sequence      |
| -------------- | ------------- |
| Enter          | `{enter}`     |
| Tab            | `{tab}`       |
| Escape         | `{esc}`       |
| Backspace      | `{backspace}` |
| Delete         | `{delete}`    |
| Arrow left     | `{left}`      |
| Arrow right    | `{right}`     |
| Arrow up       | `{up}`        |
| Arrow down     | `{down}`      |
| Home           | `{home}`      |
| End            | `{end}`       |
| Page Up        | `{pageup}`    |
| Page Down      | `{pagedown}`  |
| Shift          | `{shift}`     |
| Ctrl           | `{ctrl}`      |
| Alt            | `{alt}`       |
| Command / Meta | `{command}`   |
| F12            | `{f12}`       |
| Space          | a space       |

To press a key without typing any text, for example Escape to close a modal or an arrow key on a slider, use a Type text step on that element with only the sequence: `{esc}`. See [Pressing keys in a test](/recording-tests-steps/using-keyboard-shortcuts.md#pressing-keys-in-a-test).

To type `{{` and `}}` literally instead of inserting a variable, wrap the text in `{% raw %}` and `{% endraw %}`.

| Field              | Description                                               |
| ------------------ | --------------------------------------------------------- |
| `selector`         | Field to type into.                                       |
| `value`            | Text and key sequences to type. Required.                 |
| `has_secret_value` | `true` marks the value as secret, for example a password. |

```yaml
- action: type
  action_details:
    selector: "xpath=//input[@name='search']"
    value: "running shoes{enter}"
```

### Select option

`select` chooses one or more options in a native HTML `select` element (a dropdown or combobox). For custom dropdowns built from other elements, use Click steps instead.

You can match the option by its visible text, its `value` attribute or its position.

| Field                | Description                                                                                                  |
| -------------------- | ------------------------------------------------------------------------------------------------------------ |
| `selector`           | The `select` element.                                                                                        |
| `select_type`        | How to match the option: `text` (visible text), `value` (`value` attribute) or `index` (position). Required. |
| `value`              | The text, value or index to select. For several options, put one per line. Required.                         |
| `select_is_multiple` | `true` for a `select` that allows multiple options. Default: `false`.                                        |

```yaml
- action: select
  action_details:
    selector: "xpath=//select[@name='country']"
    select_type: value
    value: "PL"
```

Selecting several options:

```yaml
- action: select
  action_details:
    selector: "xpath=//select[@name='languages']"
    select_type: value
    select_is_multiple: true
    value: |-
      en
      pl
      de
```

### Clear input

`clear` removes all text from an `input`, `textarea` or `contenteditable` element. It takes only a `selector`.

```yaml
- action: clear
  action_details:
    selector: "xpath=//input[@name='search']"
```

### Change value

`change` sets the value of a form element at once and fires a JavaScript `change` event, without typing letter by letter. It's faster than Type text for long text, and it also works for other form controls, such as radio groups and range sliders.

Use Type text instead when your app reacts to individual key presses, for example search suggestions.

| Field              | Description                       |
| ------------------ | --------------------------------- |
| `selector`         | Form element to change.           |
| `value`            | New value.                        |
| `has_secret_value` | `true` marks the value as secret. |

### Upload file

`uploadFile` puts a file into a file input, as if the user chose it in the file dialog.

* The selector must point to the `<input type="file">` element, not to a button or label that opens the dialog.
* Any file type is allowed. The maximum file size is 10 MB.
* In the app, pick a file on the **Files library** tab or upload a new one on the **Upload new** tab; new uploads are added to the project [Files](/organizing-tests/files.md) library. To preview a file, click its name in the step details.
* The file is stored in your project. In the API and MCP, pass it as `projectArtifactId` (required). In a YAML ZIP export, the file is included in the archive and referenced with `file_source`.

```yaml
- action: uploadFile
  action_details:
    selector: "xpath=//input[@type='file']"
    file_source: "artifacts/invoice.pdf"
```

### Paste from clipboard

`pasteFromClipboard` pastes the clipboard content into the element, like Ctrl+V. Use it after a "Copy to clipboard" button in your app, to use the copied value later in the test. It takes only a `selector`.

## Window actions

### Go to URL

`goto` opens a URL in the current tab.

The step passes when the browser fires the [`DOMContentLoaded`](https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/webNavigation/onDOMContentLoaded) event. It doesn't check the HTTP status: a page that returns 404 or 500 but still loads passes. Add an [assertion](/editing-tests/assertions.md) to verify the page content.

If the site is behind [basic auth](https://en.wikipedia.org/wiki/Basic_access_authentication), turn on **Password protected** and enter the credentials.

![Go to URL step with the Password protected option](https://3168433179-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MKixgeBPbLvnD0l1eiV%2Fuploads%2F3L9o5R4LQtyhja3Td4TX%2Fimage.png?alt=media\&token=7e934628-4a92-40ac-9b0e-3836b0129602)

| Field                  | Description             |
| ---------------------- | ----------------------- |
| `url`                  | URL to open. Required.  |
| `username`, `password` | Basic auth credentials. |

```yaml
- action: goto
  action_details:
    url: "{{hostname}}/login"
```

### Go back and Go forward

`goBack` and `goForward` move through the browser history of the current tab, like the browser's back and forward buttons. They have no fields.

### New tab

`newTab` opens a URL in a new tab. It takes the same fields as Go to URL. See [Tabs & iframes](/editing-tests/tabs-and-iframes.md).

### Close tab

`closeTab` closes the active tab and switches to another open tab: the one with the next higher number, or, if there is none, the one with the next lower number. If it's the only tab, the browser closes and the test stops. It has no fields. See [Tabs & iframes](/editing-tests/tabs-and-iframes.md).

### Reload page

`reloadPage` reloads the current page. Use it when the previous step changed data that your app doesn't refresh on its own. It has no fields.

```yaml
- action: reloadPage
  action_details: {}
```

### Open inbox

`openInbox` opens a [BugBug Testing Inbox](/editing-tests/testing-inbox.md) mailbox in a new tab, so the test can read emails such as account confirmations. The next steps run in that tab. The `value` field (**Username** in the app) is the mailbox name only, the part before `@bugbug-inbox.com`, for example `{{testRunId}}` or `signup-{{testRunId}}`. Don't enter the full email address. Required.

Open inbox doesn't wait for emails: the next step, for example a click on the email's subject, waits for the email up to its timeout. See [Testing Inbox](/editing-tests/testing-inbox.md).

If you have the full address in a variable, cut the mailbox name out with a [Set variable](#set-variable) step. See [this example](/editing-tests/custom-javascript-actions.md#example-a-bugbug-inbox-mailbox-from-a-login-email).

```yaml
- action: openInbox
  action_details:
    value: "{{testRunId}}"
```

## Advanced actions

### Set variable

`setLocalVariable` saves a value to a local variable. Later steps in the same test run use it as `{{variableName}}`, also on other domains. Use it to capture text from the page, such as an order number, a price or a generated code, and use it later in the test. While recording, the same step is created by **Variables** → **Save variable for later**. See [Local variables](/editing-tests/local-variables.md).

The value can come from three sources, chosen in the **Value** field:

| **Value** in the app  | `local_variable_source` in YAML | Value comes from                                                                                              | Other field |
| --------------------- | ------------------------------- | ------------------------------------------------------------------------------------------------------------- | ----------- |
| **From element**      | `element`                       | The element on the page: its text, or for `input` and `textarea` its value, for `select` the selected option. | `selector`  |
| **Text**              | `value`                         | A fixed text, which can include other variables.                                                              | `value`     |
| **Custom JavaScript** | `evaluate`                      | The result of your JavaScript code, for example part of a text or an attribute.                               | `code`      |

```yaml
- action: setLocalVariable
  action_details:
    local_variable_name: "orderId"
    local_variable_source: element
    selector: "xpath=//*[@data-testid='order-id']"
```

### Switch context

`switchContext` moves the test to another browser tab, into an iframe, or back to the main page. See [Tabs & iframes](/editing-tests/tabs-and-iframes.md).

| Field      | Description                                                            |
| ---------- | ---------------------------------------------------------------------- |
| `tab_no`   | Number of the tab to switch to.                                        |
| `value`    | `iframe` to enter an iframe, or `topFrame` to return to the main page. |
| `selector` | The `<iframe>` element to enter. Required with `value: iframe`.        |

```yaml
- action: switchContext
  action_details:
    tab_no: 0
    value: iframe
    selector: "css=iframe#checkout"
```

### Run custom JavaScript

`execute` runs your JavaScript code in the tested page, in the browser. Use it for what other steps can't do, such as calling an API, setting `localStorage`, or preparing test data. See [Custom JavaScript actions](/editing-tests/custom-javascript-actions.md) for examples.

* **The code is the body of an async function**, `async function(variables) { ... }`, so you can use `await`.
* **Read variables through the `variables` object**, for example `variables.myVar` or `variables.testRunId`.
* **The return value is ignored.** To check something, use a [custom JavaScript assertion](/editing-tests/assertions.md) instead. To save a value for later steps, use [Set variable](#set-variable) with **Value** set to **Custom JavaScript**.
* **An error fails the test.** A thrown error or a bug in the code stops the test with the `CODE_EXECUTION_ERROR` [error code](/debugging-tests/error-codes.md) and shows the message.

```javascript
const response = await fetch('https://api.example.com/test-users');
const users = await response.json();
if (users.length === 0) {
  throw new Error('No test users available');
}
localStorage.setItem('testUser', users[0].email);
```

If the code above throws, the step fails with:

```
Your JavaScript code has an error:
"Error: No test users available ..."
```

| Field  | Description                |
| ------ | -------------------------- |
| `code` | JavaScript code. Required. |

```yaml
- action: execute
  action_details:
    code: "localStorage.setItem('cookieConsent', 'true')"
```

### Answer a prompt

`answerPrompt` answers a browser dialog opened by `alert()`, `confirm()` or `prompt()`. It's recorded automatically, so you rarely add it by hand.

| `value`  | Result                                      |
| -------- | ------------------------------------------- |
| `true`   | Confirms the dialog.                        |
| `false`  | Rejects the dialog.                         |
| Any text | Types this answer into a `prompt()` dialog. |

<figure><img src="https://3168433179-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MKixgeBPbLvnD0l1eiV%2Fuploads%2FUTqZmjEvF703V1Gfo8ld%2FScreen%20Shot%202022-10-24%20at%2017.55.38.png?alt=media&amp;token=2ee71d2d-3334-4a4a-873f-3be83ab1909e" alt="Browser confirm dialog during a test"><figcaption></figcaption></figure>

<figure><img src="https://3168433179-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MKixgeBPbLvnD0l1eiV%2Fuploads%2F3W3uT0EMTVp1wSNNSvYY%2FScreen%20Shot%202022-10-24%20at%2017.58.39.png?alt=media&amp;token=8723f786-8fb4-49b4-afcc-eb96e5b7df0f" alt="Answer a prompt step with the answer field"><figcaption></figcaption></figure>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.bugbug.io/editing-tests/actions.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.