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

# Assertions

Reference of every BugBug assertion: what each one checks, its YAML and API names, operators, expected values, how assertions are retried and compared, and case sensitivity. Includes counting elements

An assertion is a test step that checks something without interacting with the page, for example that an element shows a specific text or that the URL changed after a redirect. If the check doesn't pass, the test fails. The other kind of step is an [action](https://docs.bugbug.io/editing-tests/actions.md).

When you [record a test](https://docs.bugbug.io/recording-tests-steps/recording-assertions.md), BugBug records **Element is visible** and **Element has text** assertions. You can change any assertion to another type in the step editor, or add one manually.

<figure><img src="https://3168433179-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MKixgeBPbLvnD0l1eiV%2Fuploads%2FhlpH8pssBgh2cZtE2Hu0%2FAdd_a_new_assertions_step.png?alt=media&amp;token=f1b3014c-7bfa-41f9-bf49-bebc78b77171" alt="List of assertion types in the step editor"><figcaption><p>List of available assertions</p></figcaption></figure>

The same checks are used by [If condition](https://docs.bugbug.io/editing-tests/conditional-logic-if-else.md) steps.

## All assertions at a glance

In [YAML](https://docs.bugbug.io/export-import-and-backup/yaml-schema.md) the assertion is set with `assertion_property`, in the API and MCP with `assertionProperty`. Assertions on an element need a selector; page assertions don't.

| Assertion in the app             | `assertion_property`  | Checks  | Operators                                                                            | Expected value                       |
| -------------------------------- | --------------------- | ------- | ------------------------------------------------------------------------------------ | ------------------------------------ |
| Element is visible               | `visible`             | Element | is                                                                                   | `true`                               |
| Element is not visible           | `notVisible`          | Element | is                                                                                   | `true`                               |
| Element has text                 | `textContent`         | Element | is, is not, contains, does not contain, matches regex, is greater than, is less than | Text or number                       |
| Element is disabled              | `disabled`            | Element | is                                                                                   | `true`                               |
| Element is not disabled          | `notDisabled`         | Element | is                                                                                   | `true`                               |
| Element has attribute            | `hasAttribute`        | Element | Any, is, is not, contains, does not contain, matches regex, does not match regex     | Attribute value, or nothing with Any |
| Element does not have attribute  | `hasNotAttribute`     | Element | is                                                                                   | `true`                               |
| Form input has value             | `value`               | Element | is, is not, contains, does not contain, matches regex, is greater than, is less than | Text or number                       |
| Form input is checked            | `checked`             | Element | is                                                                                   | `true`                               |
| Form input is not checked        | `notChecked`          | Element | is                                                                                   | `true`                               |
| Page shows specific text         | `pageShowsText`       | Page    | contains                                                                             | Text                                 |
| Page does not show specific text | `pageDoesNotShowText` | Page    | does not contain                                                                     | Text                                 |
| Page has title                   | `pageTitle`           | Page    | is, is not, contains, does not contain, matches regex                                | Text                                 |
| URL address                      | `pageUrlIs`           | Page    | is, is not, contains, does not contain, matches regex                                | URL or part of it                    |
| Download started                 | `downloadStarted`     | Page    | Any, is, is not, contains, does not contain, matches regex                           | File name, or nothing with Any       |
| Custom JavaScript                | `customJavaScript`    | Element | is                                                                                   | Not used                             |
| DOM element exists               | `exist`               | Element | is                                                                                   | `true`                               |
| DOM element does not exist       | `notExist`            | Element | is                                                                                   | `true`                               |
| Number of elements in the DOM    | `count`               | Element | is, is greater than, is less than                                                    | Whole number                         |
| Variable value                   | `variableValue`       | Page    | is, is not, contains, does not contain, matches regex                                | Text                                 |
| Clipboard value                  | `clipboardValue`      | Page    | is, is not, contains, does not contain, matches regex                                | Text                                 |

To count elements, for example how many rows or search results a page shows, use **Number of elements in the DOM** (`count`). See [Count elements](#number-of-elements-in-the-dom).

### Operators

| Operator in the app  | `assertion_type` | Passes when the current value…                         |
| -------------------- | ---------------- | ------------------------------------------------------ |
| is                   | `equal`          | Is exactly the expected value.                         |
| is not               | `notEqual`       | Is different from the expected value.                  |
| contains             | `contain`        | Contains the expected value.                           |
| does not contain     | `notContain`     | Doesn't contain the expected value.                    |
| matches regex        | `match`          | Matches the regular expression.                        |
| does not match regex | `notMatch`       | Doesn't match the regular expression.                  |
| is greater than      | `greaterThan`    | Is a number greater than the expected number.          |
| is less than         | `lessThan`       | Is a number less than the expected number.             |
| Any                  | `any`            | Always, if the attribute exists or a download started. |

### Fields

| YAML                         | API                        | Description                                                                                      |
| ---------------------------- | -------------------------- | ------------------------------------------------------------------------------------------------ |
| `assertion_property`         | `assertionProperty`        | What to check. Required.                                                                         |
| `assertion_type`             | `assertionType`            | Operator. Required.                                                                              |
| `assertion_expected_value`   | `assertionExpectedValue`   | Expected value. Can include [variables](https://docs.bugbug.io/editing-tests/variables.md).      |
| `assertion_attribute_name`   | `assertionAttributeName`   | Attribute name, for Element has attribute and Element does not have attribute.                   |
| `assertion_java_script`      | `assertionJavaScript`      | Code, for Custom JavaScript.                                                                     |
| `assertion_variable_name`    | `assertionVariableName`    | Variable name, for Variable value.                                                               |
| `assertion_case_insensitive` | `assertionCaseInsensitive` | Ignore letter case. See [Case-insensitive text comparisons](#case-insensitive-text-comparisons). |
| `selector`                   | `selectorsPresets`         | The element, for element assertions.                                                             |

```yaml
- action: assert
  action_details:
    selector: "xpath=//h1"
    assertion_property: textContent
    assertion_type: contain
    assertion_expected_value: "Dashboard"
```

## How assertions are checked

* **Failed checks are retried.** If an assertion doesn't pass, BugBug checks again every 1.5 seconds until the step's timeout. The test fails only when the timeout is reached. One exception: Variable value with a variable that doesn't exist fails at once.
* **Text is normalized.** Before comparing, BugBug trims spaces, decodes HTML entities, applies Unicode NFKC normalization and removes zero-width characters, in both the current and the expected value. URLs are also URL-decoded.
* **Regular expressions search anywhere in the value.** `match` uses a JavaScript regular expression and passes if it matches any part of the value. Use `^` and `$` to match the whole value. Surrounding slashes are optional (`/abc/` works like `abc`), but flags such as `/abc/i` aren't supported: use [Case-insensitive](#case-insensitive-text-comparisons) instead.
* **Numbers are read from the start of the text.** *is greater than* and *is less than* read a number with `parseFloat`: `123 USD` is read as `123`, but `USD 123` isn't a number and fails.
* **Several matching elements.** If the selector matches more than one element, BugBug checks the first one. Only Number of elements in the DOM counts all of them.

## Assertion details

### Element is visible and Element is not visible

**Element is visible** passes when the element is at least partly visible on the screen and not covered by another element. **Element is not visible** passes when the element is hidden, outside the viewport, or covered by another element.

To check that an element is gone from the page completely, use **DOM element does not exist**.

### Element has text

Compares the element's `textContent`, not `innerText`: all text inside the element, including text in hidden child elements, without the content of `style` elements. If the element has a Shadow DOM, the text of its shadow root is used. Use **Page shows specific text** to search the whole page.

### Element is disabled and Element is not disabled

Check the element's `disabled` property, so they work with native form elements that have the `disabled` attribute, such as `button`, `input` or `select`. `aria-disabled` and CSS styles aren't taken into account. To check `aria-disabled`, use **Element has attribute**.

### Element has attribute and Element does not have attribute

**Element has attribute** first requires the attribute to exist, then compares its value. With **Any** it only checks that the attribute exists. **Element does not have attribute** passes only when the attribute is missing; the element itself must exist.

An attribute with an empty value, such as `disabled=""`, exists. The attribute name has up to 128 characters and can't contain spaces, quotes, `/`, `>` or `=`.

```yaml
- action: assert
  action_details:
    selector: "css=button[type='submit']"
    assertion_property: hasAttribute
    assertion_attribute_name: "data-state"
    assertion_type: equal
    assertion_expected_value: "ready"
```

Use these assertions to check accessibility attributes such as `aria-label`, `aria-expanded` or `role`. To scan a whole page for WCAG issues with axe-core, use the [Accessibility check](https://docs.bugbug.io/accessibility-testing/accessibility-testing.md) step.

### Form input has value

Compares the element's `value` property, for example the text in an `input` or the selected option of a `select`.

* **Radio buttons:** it reads the `value` of the matched input, not which radio in the group is selected. To check a selection, use **Form input is checked** on the radio you expect.
* **Select with `multiple`:** `value` is the value of the first selected option only. To check all selected options, use **Custom JavaScript**, for example `return [...element.selectedOptions].map((o) => o.value).join(',') === 'red,blue';`.

### Page shows specific text and Page does not show specific text

Search the text of the whole page, including Shadow DOM, without the content of `script` and `style` elements. Text hidden with CSS is also found.

### Download started

Checks the most recent file downloaded since the test run started. It doesn't matter which step or which iframe started the download. With **Any** it passes if any download started; other operators compare the file name, for example `contains` `.pdf`. An empty current value means that nothing was downloaded.

It doesn't check that the download finished or that the file is correct.

### Custom JavaScript

Runs your JavaScript code and passes when it returns `true`.

* The code is the body of `async function(selector, variables) { ... }`, so you can use `await`.
* Inside the code you can use `element` (the element matched by the selector), `selector` (the selector text) and `variables` (an object with all [variables](https://docs.bugbug.io/editing-tests/variables.md), for example `variables.testRunId`).
* The assertion needs a selector. For a check that isn't about one element, use `css=body`.
* The code must return a boolean. Any other value, such as `"true"`, `1` or `undefined`, fails with the `INVALID_EXECUTION_RESULT` [error code](https://docs.bugbug.io/debugging-tests/error-codes.md). An error in the code fails with `CODE_EXECUTION_ERROR`.
* The expected value isn't used.

```javascript
return element.placeholder === 'Username';
```

```yaml
- action: assert
  action_details:
    selector: "css=body"
    assertion_property: customJavaScript
    assertion_type: equal
    assertion_java_script: "return document.readyState === 'complete'"
```

See [Custom JavaScript actions](https://docs.bugbug.io/editing-tests/custom-javascript-actions.md) for more examples.

### Number of elements in the DOM

The count assertion. It counts all elements that match the selector, visible or not, and compares the number with the expected whole number. Use it to check how many rows, list items, search results or cart items there are, or that a list isn't empty.

| To check that…                  | Operator        | Expected value |
| ------------------------------- | --------------- | -------------- |
| The table has exactly 10 rows   | is              | `10`           |
| The search returned any results | is greater than | `0`            |
| The cart has fewer than 5 items | is less than    | `5`            |

Make the selector match exactly the elements you want to count, for example `css=table#orders tbody tr` rather than `css=tr`.

```yaml
- action: assert
  action_details:
    selector: "css=.todo-item"
    assertion_property: count
    assertion_type: greaterThan
    assertion_expected_value: 0
```

### Variable value

Compares the current value of a variable, set in `assertion_variable_name` without curly brackets. If the variable doesn't exist, the step fails immediately.

```yaml
- action: assert
  action_details:
    assertion_property: variableValue
    assertion_variable_name: "orderId"
    assertion_type: match
    assertion_expected_value: "^[A-Z0-9-]+$"
```

### Clipboard value

Compares the text that the tested page copied to the clipboard during the test run, for example after a "Copy link" button. BugBug doesn't read your system clipboard. It records text that the page copies with:

* `navigator.clipboard.writeText()`,
* `navigator.clipboard.write()`, plain text only,
* `document.execCommand('copy')`, the selected text.

Things to know:

* **Secure pages only.** Browsers offer the Clipboard API only on secure pages, such as HTTPS or `localhost`. On an HTTP page BugBug doesn't record any copy, so the value is empty and the assertion fails.
* **Keyboard copying isn't recorded.** Text copied with Ctrl+C or the browser menu isn't recorded.
* **It's retried** like other assertions, until the step's timeout.

The same value is used by the [Paste from clipboard](https://docs.bugbug.io/editing-tests/actions.md) action.

```yaml
- action: assert
  action_details:
    assertion_property: clipboardValue
    assertion_type: contain
    assertion_expected_value: "https://"
```

## Case-insensitive text comparisons

Select **Case-insensitive** in the step editor to ignore letter case. For example, **is** `Welcome` also accepts `WELCOME`. For regular expressions it works like the `i` flag.

It's available for text comparisons (**is**, **is not**, **contains**, **does not contain**, **matches regex**, **does not match regex**) on element text, form values, attribute values, page titles, URLs, page text, variables, clipboard values and downloaded file names. It also works in [If condition](https://docs.bugbug.io/editing-tests/conditional-logic-if-else.md) steps. It doesn't apply to numbers, element counts, visibility, existence, checked or disabled states, or Custom JavaScript.

Steps without a saved setting keep their previous behavior:

| Comparison                                                         | Default          |
| ------------------------------------------------------------------ | ---------------- |
| **is**, **is not**, **matches regex**, **does not match regex**    | Case-sensitive   |
| **contains**, **does not contain**                                 | Case-insensitive |
| **Page shows specific text**, **Page does not show specific text** | Case-sensitive   |

In YAML use `assertion_case_insensitive`, in the [Public API](https://docs.bugbug.io/integrations/public-api.md) `assertionCaseInsensitive`. `null` or no value keeps the default above.

<details>

<summary>Extension version requirements</summary>

Local and cloud runs need an extension that supports this setting. Older extensions silently use the default behavior, including for settings saved through the API, YAML or MCP, which can give different results in local and cloud runs. If the installed extension is too old, the checkbox is disabled and shows an update message.

Update the local extension before running these steps. For cloud runs, administrators must also update older extension pins on the suite, project, organization or global configuration. Suite pins take precedence over project pins, then organization pins, then global configuration.

</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/assertions.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.
