> 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/local-variables.md).

# Local variables

Save a value from the page during a test, such as an order number or a price, and use it in later steps: capture, extract or store text from an element while recording or with a Set variable step.

A local variable holds a value saved during a test run, for example an order number, a generated email address or a price shown on the page. You choose the variable's name when you save it, for example `orderId`. Later steps in the same run use the value by putting that name in double curly brackets: `{{orderId}}`. It works like any other [variable](https://docs.bugbug.io/editing-tests/variables.md).

{% hint style="info" %}
**In short**

* A local variable is saved by a [Set variable](https://docs.bugbug.io/editing-tests/actions.md#set-variable) step. Record it with **Save variable for later**, or add the step manually.
* You give it a name, such as `orderId`, and use it later as `{{orderId}}`.
* The value comes from an element on the page (**From element**), a fixed text (**Text**) or your code (**Custom JavaScript**).
* It exists only during the test run, in the steps after the Set variable step. A step that uses it earlier fails with `VARIABLE_DOES_NOT_EXIST`.
* It works across tabs and domains within the run.
* A local variable with the same name as a project or built-in variable replaces it for the rest of the run.
  {% endhint %}

## Capture text from the page while recording

1. While recording, click **Variables** in the BugBug overlay.
2. Click **Save variable for later**.
3. Click the element whose text you want to save, for example the order number on a confirmation page.
4. Enter a name for the variable, for example `orderId`, and click **Save variable**. The name can contain only letters and digits. If you don't change it, the name is `savedVariable`.

<figure><img src="https://3168433179-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MKixgeBPbLvnD0l1eiV%2Fuploads%2FzXt74muO2oZ029AEiahi%2F1_recorder.png?alt=media&amp;token=6e5c59cf-bf71-45f1-8a51-af54048bc1c8" alt="Variables button in the recording overlay" width="284"><figcaption><p>Variables button in the recording overlay</p></figcaption></figure>

<figure><img src="https://3168433179-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MKixgeBPbLvnD0l1eiV%2Fuploads%2FFDlqqL5U1IM7gdyr5ioH%2FZrzut%20ekranu%202023-04-03%20120138.png?alt=media&amp;token=713c1990-5c94-453b-9bc0-deb0cb3c723d" alt="Save variable for later and Insert variable options"><figcaption></figcaption></figure>

<figure><img src="https://3168433179-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MKixgeBPbLvnD0l1eiV%2Fuploads%2FQdEsHgQ75H4HLOS3PDRh%2F3_saveForLater.png?alt=media&amp;token=f1804c1f-f448-41eb-87cb-9612df3701fd" alt="Clicking the element whose text is saved"><figcaption><p>Click the element with the text you want to save</p></figcaption></figure>

<figure><img src="https://3168433179-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MKixgeBPbLvnD0l1eiV%2Fuploads%2FCsxfMkjlyduJ7KZwsRfr%2F4_saveForLater.png?alt=media&amp;token=c0535a58-54c3-4245-bc6d-dffcf04cec02" alt="Naming the saved variable in the overlay"><figcaption><p>Name the variable</p></figcaption></figure>

BugBug records a **Set variable** step with **Value** set to **From element** and the element's selector. When the test runs, the step reads the element again, so the variable gets the value shown in that run, not the one you saw while recording.

**From element** saves:

| Element             | Saved value         |
| ------------------- | ------------------- |
| `input`, `textarea` | The field's value   |
| `select`            | The selected option |
| Any other element   | The element's text  |

<figure><img src="https://3168433179-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MKixgeBPbLvnD0l1eiV%2Fuploads%2FtSzKRtcGOaBOPau7cVLA%2Fset%20variable.png?alt=media&amp;token=fe70fe60-180c-466b-971d-4e69301a8974" alt="Recorded Set variable step in the test"><figcaption><p>Recorded Set variable step</p></figcaption></figure>

After recording, you can change the variable's name or selector in the step's details.

## Insert a variable while recording

To type the value of a variable into a field while recording:

1. Click **Variables** → **Insert variable** in the overlay.
2. Select the variable. The list has your local variables, project variables and built-in variables, with their current values, and you can search it by name.
3. Click the input field.

BugBug records a **Type text** step whose value is the selected variable's name in double curly brackets, for example `{{orderId}}`. When the test runs, the variable's value from that run is typed.

Some variables are shown with **(computed while running)** instead of a value: their value is known only when the test runs.

<figure><img src="https://3168433179-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MKixgeBPbLvnD0l1eiV%2Fuploads%2Ffdtbsex1j77lbwFzgZbC%2FInsert%20variable.png?alt=media&amp;token=fed2a6b6-a490-4da1-8b52-48146cee592a" alt="Insert variable menu in the recording overlay"><figcaption></figcaption></figure>

## Add a Set variable step manually

1. In the test, add a new step and choose **Set variable**.
2. Enter the **Variable name**, for example `orderId`.
3. Choose where the **Value** comes from:
   * **From element**: the element's text or value. Set its selector.
   * **Text**: a fixed text, which can include other variables, for example `{{firstName}} {{lastName}}`.
   * **Custom JavaScript**: the value your code returns. See [Custom JavaScript actions](https://docs.bugbug.io/editing-tests/custom-javascript-actions.md).

<figure><img src="https://3168433179-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MKixgeBPbLvnD0l1eiV%2Fuploads%2FG1dh8mjDTmYQ5VShouen%2FZrzut%20ekranu%202023-04-11%20105752.png?alt=media&amp;token=4cc37aab-67f4-4ed9-959d-f09034a9cc3b" alt="Set variable step form"><figcaption></figcaption></figure>

In [YAML](https://docs.bugbug.io/export-import-and-backup/yaml-schema.md), the step is `setLocalVariable`:

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

`local_variable_source` is `element`, `value` (Text) or `evaluate` (Custom JavaScript).

## Use a local variable

The examples below use a local variable named `orderId`. Use the name you gave your variable.

* **In step fields and selectors:** `{{orderId}}`, for example in Type text, an assertion's expected value or a custom selector such as `//tr[contains(., "{{orderId}}")]`.
* **In JavaScript code:** `variables.orderId`. `{{orderId}}` isn't replaced inside code.
* **To check its value:** a **Variable value** [assertion](https://docs.bugbug.io/editing-tests/assertions.md#variable-value).

The saved value is shown in the Set variable step's details in the run.

### Example: check that a new order appears in the order list

1. After placing the order, add a **Set variable** step: name `orderId`, **Value** **From element**, selector of the order number on the confirmation page.
2. Go to the order list.
3. Add a **Page shows specific text** assertion with `{{orderId}}`.

## Rules

* **Order matters.** A local variable exists from its Set variable step until the end of the test run. Steps before it can't use it.
* **One run only.** The value isn't kept after the run and isn't shared with other tests. Every run saves it again.
* **Same name, new value.** A later Set variable step with the same name replaces the value.
* **Overrides other variables.** A local variable with the name of a project, profile or built-in variable replaces that variable for the rest of the run. Use unique names to avoid this.
* **Values are text.** A JavaScript result that is an object or array is saved as JSON text.

## FAQ

<details>

<summary>How do I capture text from an element and use it later in the test?</summary>

Add a **Set variable** step with **Value** set to **From element** and the element's selector, or record it with **Variables** → **Save variable for later**. Give the variable a name, for example `orderId`, and use it in later steps as `{{orderId}}`.

</details>

<details>

<summary>How do I save only part of the text, or an attribute such as href?</summary>

Use a **Set variable** step with **Value** set to **Custom JavaScript** and return the part you need, for example:

```javascript
return document.querySelector('.order-number').textContent.match(/\d+/)[0];
```

```javascript
return document.querySelector('a.confirm').getAttribute('href');
```

</details>

<details>

<summary>Can another test use my local variable?</summary>

No. A local variable exists only in the test run that saves it. To share a value between tests, use a [project variable](https://docs.bugbug.io/editing-tests/variables.md) or get the value again in each test.

</details>

<details>

<summary>Why does a step fail with VARIABLE_DOES_NOT_EXIST?</summary>

The step uses a variable that hasn't been saved yet in this run, or its name is spelled differently. Names are case-sensitive. Make sure the Set variable step comes before the step that uses the variable. See [error codes](https://docs.bugbug.io/debugging-tests/error-codes.md).

</details>

<details>

<summary>Can I use a local variable on another domain or in a new tab?</summary>

Yes. Local variables are kept for the whole run, across tabs and domains.

</details>


---

# 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/local-variables.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.
