Retrying Assertions on Grafana Labs

toBeChecked()

Mon, 21 Sep 2026 15:16:28 +0000

toBeChecked()

The toBeChecked() method asserts that a checkbox or radio button is checked. This is a retrying assertion that automatically waits for the element to become checked.

Syntax

await expect(locator).toBeChecked();
await expect(locator).not.toBeChecked();
await expect(locator).toBeChecked(options);

Parameters

Parameter	Type	Description
options	RetryConfig	Optional configuration options

Returns

Type	Description
Promise	A promise that resolves when the assertion passes

Description

The toBeChecked() method checks if a checkbox or radio button is checked. This assertion is specifically designed for form elements that have a checked state.

This is a retrying assertion that will automatically re-check the element’s state until it becomes checked or the timeout is reached.

Usage

import { browser } from 'k6/browser';
import { expect } from 'https://jslib.k6.io/k6-testing/0.6.1/index.js';

export const options = {
  scenarios: {
    ui: {
      executor: 'shared-iterations',
      options: {
        browser: {
          type: 'chromium',
        },
      },
    },
  }
};

export default async function () {
  const page = await browser.newPage();

  // Go to a test page that demonstrates checkbox functionality
  await page.goto('https://quickpizza.grafana.com');

  // Check a checkbox
  await page.locator('#accept-terms').check();
  await expect(page.locator('#accept-terms')).toBeChecked();

  // Check a radio button
  await page.locator('input[name="gender"][value="male"]').check();
  await expect(page.locator('input[name="gender"][value="male"]')).toBeChecked();

  // Verify another option is not checked
  await expect(page.locator('input[name="gender"][value="female"]')).not.toBeChecked();
}

toBeDisabled()

Mon, 21 Sep 2026 15:16:28 +0000

toBeDisabled()

The toBeDisabled() method asserts that an element is disabled. This is a retrying assertion that automatically waits for the element to become disabled.

Syntax

await expect(locator).toBeDisabled();
await expect(locator).not.toBeDisabled();
await expect(locator).toBeDisabled(options);

Parameters

Parameter	Type	Description
options	RetryConfig	Optional configuration options

Returns

Type	Description
Promise	A promise that resolves when the assertion passes

Description

The toBeDisabled() method checks if an element is disabled. An element is considered disabled if it has the disabled attribute or property set to true.

This is a retrying assertion that will automatically re-check the element’s disabled state until it becomes disabled or the timeout is reached.

Usage

import { browser } from 'k6/browser';
import { expect } from 'https://jslib.k6.io/k6-testing/0.6.1/index.js';

export const options = {
  scenarios: {
    ui: {
      executor: 'shared-iterations',
      options: {
        browser: {
          type: 'chromium',
        },
      },
    },
  }
};

export default async function () {
  const page = await browser.newPage();
  await page.goto('https://quickpizza.grafana.com/');

  // Click the pizza button to see the recommendation
  await page.locator('button[name="pizza-please"]').click();

  // Wait for the recommendation to appear
  await expect(page.locator('h2[id="pizza-name"]')).toBeVisible();

  // The pizza button should now be disabled (no longer clickable)
  await expect(page.locator('button[name="pizza-please"]')).toBeDisabled();

  // Verify that we can check for disabled state
  await expect(page.locator('button[name="pizza-please"]')).not.toBeEnabled();
}

toBeEditable()

Mon, 21 Sep 2026 15:16:28 +0000

toBeEditable()

The toBeEditable() method asserts that an element is editable. This is a retrying assertion that automatically waits for the element to become editable.

Syntax

await expect(locator).toBeEditable();
await expect(locator).not.toBeEditable();
await expect(locator).toBeEditable(options);

Parameters

Parameter	Type	Description
options	RetryConfig	Optional configuration options

Returns

Type	Description
Promise	A promise that resolves when the assertion passes

Description

The toBeEditable() method checks if an element is editable. An element is considered editable if it can receive user input. This includes:

Input fields that are not disabled or readonly
Textareas that are not disabled or readonly
Elements with contenteditable="true"

This is a retrying assertion that will automatically re-check the element’s editable state until it becomes editable or the timeout is reached.

Usage

import { browser } from 'k6/browser';
import { expect } from 'https://jslib.k6.io/k6-testing/0.6.1/index.js';

export const options = {
  scenarios: {
    ui: {
      executor: 'shared-iterations',
      options: {
        browser: {
          type: 'chromium',
        },
      },
    },
  }
};

export default async function () {
  const page = await browser.newPage();

  // Go to a test page that demonstrates editable functionality
  await page.goto('https://quickpizza.grafana.com/login');

  // Check that input fields are editable
  await expect(page.locator('#username')).toBeEditable();
  await expect(page.locator('#password')).toBeEditable();
  await expect(page.locator('#message')).toBeEditable();

  // Check readonly field is not editable
  await expect(page.locator('#readonly-field')).not.toBeEditable();

  // Check contenteditable elements
  await expect(page.locator('[contenteditable="true"]')).toBeEditable();
  await expect(page.locator('[contenteditable="false"]')).not.toBeEditable();
}

toBeEmpty()

Mon, 21 Sep 2026 15:16:28 +0000

toBeEmpty()

The toBeEmpty() method asserts that an element is empty. It automatically retries the assertion until the element becomes empty or the timeout is reached.

Syntax

await expect(locator).toBeEmpty();
await expect(locator).not.toBeEmpty();
await expect(locator).toBeEmpty(options);

Parameters

Parameter	Type	Description
options	RetryConfig	Optional configuration options

Returns

Type	Description
Promise	A promise that resolves when the assertion passes

Description

The toBeEmpty() method checks if an element is empty. An element is considered empty if:

For input elements: the value is an empty string ("")
For other elements: the text content is empty (no visible text)

This method automatically retries the assertion until the element’s content becomes empty or the timeout is reached.

Usage

import { browser } from 'k6/browser';
import { expect } from 'https://jslib.k6.io/k6-testing/0.6.1/index.js';

export const options = {
  scenarios: {
    ui: {
      executor: 'shared-iterations',
      options: {
        browser: {
          type: 'chromium',
        },
      },
    },
  }
};

export default async function () {
  const page = await browser.newPage();
  await page.goto('https://quickpizza.grafana.com/');

  // Click on the advanced checkbox
  await page.locator('label div').click();

  // Check that an input field is empty
  await expect(page.locator('#pizza-name')).toBeEmpty();

  // Fill input and then verify it's not empty
  await page.locator('#pizza-name').fill('my pizza');
  await expect(page.locator('#pizza-name')).not.toBeEmpty();
}

toBeHidden()

Mon, 21 Sep 2026 15:16:28 +0000

toBeHidden()

The toBeHidden() method asserts that an element is hidden on the page. This is a retrying assertion that automatically waits for the element to become hidden.

Syntax

await expect(locator).toBeHidden();
await expect(locator).not.toBeHidden();
await expect(locator).toBeHidden(options);

Parameters

Parameter	Type	Description
options	RetryConfig	Optional configuration options

Returns

Type	Description
Promise	A promise that resolves when the assertion passes

Description

The toBeHidden() method checks if an element is hidden on the page. An element is considered hidden if:

It does not exist in the DOM
It has zero dimensions
It is hidden by CSS (display: none, visibility: hidden, etc.)
It is outside the viewport bounds

This is a retrying assertion that will automatically re-check the element’s visibility until it becomes hidden or the timeout is reached.

Usage

import { browser } from 'k6/browser';
import { expect } from 'https://jslib.k6.io/k6-testing/0.6.1/index.js';

export const options = {
  scenarios: {
    ui: {
      executor: 'shared-iterations',
      options: {
        browser: {
          type: 'chromium',
        },
      },
    },
  }
};

export default async function () {
  const page = await browser.newPage();
  await page.goto('https://quickpizza.grafana.com/');

  // Check that non-existent elements are hidden
  await expect(page.locator('.error-message')).toBeHidden();
  await expect(page.locator('.loading-spinner')).toBeHidden();

  // Click the pizza button to show the recommendation
  await page.locator('button[name="pizza-please"]').click();

  // Wait for the recommendation to appear
  await expect(page.locator('h2[id="pizza-name"]')).not.toBeHidden();

  // Verify the button is no longer visible after clicking
  await expect(page.locator('button[name="pizza-please"]')).toBeHidden();
}

toBeVisible()

Mon, 21 Sep 2026 15:16:28 +0000

toBeVisible()

The toBeVisible() method asserts that an element is visible on the page. This is a retrying assertion that automatically waits for the element to become visible.

Syntax

await expect(locator).toBeVisible();
await expect(locator).not.toBeVisible();
await expect(locator).toBeVisible(options);

Parameters

Parameter	Type	Description
options	RetryConfig	Optional configuration options

Returns

Type	Description
Promise	A promise that resolves when the assertion passes

Description

The toBeVisible() method checks if an element is visible on the page. An element is considered visible if:

It exists in the DOM
It has non-zero dimensions
It is not hidden by CSS (display: none, visibility: hidden, etc.)
It is not outside the viewport bounds

This is a retrying assertion that will automatically re-check the element’s visibility until it becomes visible or the timeout is reached.

Usage

import { browser } from 'k6/browser';
import { expect } from 'https://jslib.k6.io/k6-testing/0.6.1/index.js';

export const options = {
  scenarios: {
    ui: {
      executor: 'shared-iterations',
      options: {
        browser: {
          type: 'chromium',
        },
      },
    },
  }
};

export default async function () {
  const page = await browser.newPage();
  await page.goto('https://quickpizza.grafana.com/');

  // Wait for element to be visible
  await expect(page.locator('h1')).toBeVisible();
  await expect(page.locator('button[name="pizza-please"]')).toBeVisible();
}

toHaveText()

Mon, 21 Sep 2026 15:16:28 +0000

toHaveText()

The toHaveText() method asserts that an element has specific text content. This is a retrying assertion that automatically waits for the element to have the expected text.

Syntax

await expect(locator).toHaveText(expected);
await expect(locator).not.toHaveText(expected);
await expect(locator).toHaveText(expected, options);

Parameters

Parameter	Type	Description
expected	string \| RegExp \| Array	The expected text content
options	object	Optional configuration options

Options

This method accepts all RetryConfig properties plus:

Property	Type	Default	Description
useInnerText	boolean	`false`	Use innerText instead of textContent

Returns

Type	Description
Promise	A promise that resolves when the assertion passes

Description

The toHaveText() method checks if an element has specific text content. By default, it uses textContent which includes all text nodes, including hidden ones. When useInnerText is true, it uses innerText which only includes visible text.

This is a retrying assertion that will automatically re-check the element’s text content until it matches the expected value or the timeout is reached.

Usage

import { browser } from 'k6/browser';
import { expect } from 'https://jslib.k6.io/k6-testing/0.6.1/index.js';

export const options = {
  scenarios: {
    ui: {
      executor: 'shared-iterations',
      options: {
        browser: {
          type: 'chromium',
        },
      },
    },
  }
};

export default async function () {
  const page = await browser.newPage();
  await page.goto('https://quickpizza.grafana.com/');

  // Check exact text content
  await expect(page.locator('h1')).toHaveText('Looking to break out of your pizza routine?');

  // Click the pizza button to get a recommendation
  await page.locator('button[name="pizza-please"]').click();

  // Check the recommendation header text
  await expect(page.locator('h2')).toHaveText('QuickPizza has your back!');
}

toContainText()

Mon, 21 Sep 2026 15:16:28 +0000

toContainText()

The toContainText() method asserts that an element contains specific text as a substring. This is a retrying assertion that automatically waits for the element to contain the expected text.

Syntax

await expect(locator).toContainText(expected);
await expect(locator).not.toContainText(expected);
await expect(locator).toContainText(expected, options);

Parameters

Parameter	Type	Description
expected	string \| RegExp	The text to search for
options	object	Optional configuration options

Options

This method accepts all RetryConfig properties plus:

Property	Type	Default	Description
useInnerText	boolean	`false`	Use innerText instead of textContent

Returns

Type	Description
Promise	A promise that resolves when the assertion passes

Description

The toContainText() method checks if an element contains specific text as a substring. Unlike toHaveText(), which requires exact text matching, toContainText() succeeds if the expected text is found anywhere within the element’s text content.

By default, it uses textContent which includes all text nodes, including hidden ones. When useInnerText is true, it uses innerText which only includes visible text.

This is a retrying assertion that will automatically re-check the element’s text content until it contains the expected text or the timeout is reached.

Usage

import { browser } from 'k6/browser';
import { expect } from 'https://jslib.k6.io/k6-testing/0.6.1/index.js';

export const options = {
  scenarios: {
    ui: {
      executor: 'shared-iterations',
      options: {
        browser: {
          type: 'chromium',
        },
      },
    },
  }
};

export default async function () {
  const page = await browser.newPage();
  await page.goto('https://quickpizza.grafana.com/');

  // Check that elements contain expected text
  await expect(page.locator('h1')).toContainText('pizza');
  await expect(page.locator('h1')).toContainText('routine');

  // Click the pizza button to get a recommendation
  await page.locator('button[name="pizza-please"]').click();

  // Check that the recommendation contains expected text
  await expect(page.locator('h2')).toContainText('QuickPizza');
}

toBeEnabled()

Mon, 21 Sep 2026 15:16:28 +0000

toBeEnabled()

The toBeEnabled() method asserts that an element is enabled and interactive. This is a retrying assertion that automatically waits for the element to become enabled.

Syntax

await expect(locator).toBeEnabled();
await expect(locator).not.toBeEnabled();
await expect(locator).toBeEnabled(options);

Parameters

Parameter	Type	Description
options	RetryConfig	Optional configuration options

Returns

Type	Description
Promise	A promise that resolves when the assertion passes

Description

The toBeEnabled() method checks if an element is enabled and interactive. An element is considered enabled if:

It exists in the DOM
It does not have the disabled attribute
It is not disabled through CSS or JavaScript
It can receive user interactions

This is a retrying assertion that will automatically re-check the element’s enabled state until it becomes enabled or the timeout is reached.

Usage

import { browser } from 'k6/browser';
import { expect } from 'https://jslib.k6.io/k6-testing/0.6.1/index.js';

export const options = {
  scenarios: {
    ui: {
      executor: 'shared-iterations',
      options: {
        browser: {
          type: 'chromium',
        },
      },
    },
  }
};

export default async function () {
  const page = await browser.newPage();
  await page.goto('https://quickpizza.grafana.com/');

  // Check that the pizza button is enabled
  await expect(page.locator('button[name="pizza-please"]')).toBeEnabled();

  // Check that buttons are generally enabled on the page
  await expect(page.locator('button')).toBeEnabled();
}

toHaveAttribute()

Mon, 21 Sep 2026 15:16:28 +0000

toHaveAttribute()

The toHaveAttribute() method asserts that an element has a specific attribute and optionally a specific value. This is a retrying assertion that automatically waits for the element to have the expected attribute.

Syntax

await expect(locator).toHaveAttribute(attribute);
await expect(locator).toHaveAttribute(attribute, value);
await expect(locator).toHaveAttribute(attribute, value, options);
await expect(locator).not.toHaveAttribute(attribute);

Parameters

Parameter	Type	Description
attribute	string	The attribute name to check for
value	string	Optional. The expected attribute value
options	RetryConfig	Optional configuration options

Returns

Type	Description
Promise	A promise that resolves when the assertion passes

Description

The toHaveAttribute() method checks if an element has a specific attribute. When called with just an attribute name, it verifies the attribute exists regardless of its value. When called with both attribute name and value, it verifies the attribute exists and has the exact specified value.

This is a retrying assertion that will automatically re-check the element’s attributes until the condition is met or the timeout is reached.

Usage

import { browser } from 'k6/browser';
import { expect } from 'https://jslib.k6.io/k6-testing/0.6.1/index.js';

export const options = {
  scenarios: {
    ui: {
      executor: 'shared-iterations',
      options: {
        browser: {
          type: 'chromium',
        },
      },
    },
  }
};

export default async function () {
  const page = await browser.newPage();
  await page.goto('https://quickpizza.grafana.com/');

  // Check that the pizza button has specific attributes
  await expect(page.locator('button[name="pizza-please"]')).toHaveAttribute('name', 'pizza-please');
  await expect(page.locator('button[name="pizza-please"]')).toHaveAttribute('type', 'button');

  // Check that the main heading has expected attributes
  await expect(page.locator('h1')).toHaveAttribute('class');

  // Click the pizza button to get a recommendation
  await page.locator('button[name="pizza-please"]').click();

  // Check that the recommendation heading has an id attribute
  await expect(page.locator('h2[id="pizza-name"]')).toHaveAttribute('id', 'pizza-name');

  // Check absence of attribute on non-existent elements
  await expect(page.locator('h1')).not.toHaveAttribute('disabled');
}

toHaveValue()

Mon, 21 Sep 2026 15:16:28 +0000

toHaveValue()

The toHaveValue() method asserts that an element has a specific value. This is a retrying assertion that automatically waits for the element to have the expected value.

Syntax

await expect(locator).toHaveValue(value);
await expect(locator).not.toHaveValue(value);
await expect(locator).toHaveValue(value, options);

Parameters

Parameter	Type	Description
value	string	The expected value
options	RetryConfig	Optional configuration options

Returns

Type	Description
`Promise<void>`	A promise that resolves when the assertion passes

Description

The toHaveValue() method checks if an element has a specific value. This is primarily used for form elements like input fields, textareas, and select elements. The method compares the element’s current value with the expected value.

This is a retrying assertion that will automatically re-check the element’s value until it matches the expected value or the timeout is reached.

Usage

import { browser } from 'k6/browser';
import { expect } from 'https://jslib.k6.io/k6-testing/0.6.1/index.js';

export const options = {
  scenarios: {
    ui: {
      executor: 'shared-iterations',
      options: {
        browser: {
          type: 'chromium',
        },
      },
    },
  }
};

export default async function () {
  const page = await browser.newPage();

  // Go to a test page that demonstrates input functionality
  await page.goto('https://quickpizza.grafana.com/login');

  // Fill input and check value
  await page.locator('#username').fill('testuser');
  await expect(page.locator('#username')).toHaveValue('testuser');

  // Check textarea value
  await page.locator('#message').fill('Hello world!');
  await expect(page.locator('#message')).toHaveValue('Hello world!');

  // Check select option value
  await page.locator('#country').selectOption('us');
  await expect(page.locator('#country')).toHaveValue('us');

  // Check initial empty values
  await expect(page.locator('#empty-field')).toHaveValue('');

  // Check that field doesn't have specific value
  await expect(page.locator('#username')).not.toHaveValue('wronguser');
}

toHaveTitle()

Mon, 21 Sep 2026 15:16:28 +0000

toHaveTitle()

The toHaveTitle() method asserts that a page has a specific title. This is a retrying assertion that automatically waits for the page to have the expected title.

Syntax

await expect(page).toHaveTitle(expected);
await expect(page).not.toHaveTitle(expected);
await expect(page).toHaveTitle(expected, options);

Parameters

Parameter	Type	Description
expected	string \| RegExp	The expected title
options	RetryConfig	Optional configuration options

Returns

Type	Description
Promise	A promise that resolves when the assertion passes

Description

The toHaveTitle() method checks if a page has a specific title. It retrives the title from the page’s <title> element in the document’s <head>.

When a string is provided, it performs an exact match. When a RegExp is provided, it tests the title against the regular expression pattern.

This is a retrying assertion that will automatically re-check the page’s title until it matches the expected value or the timeout is reached.

Usage

import { browser } from 'k6/browser';
import { expect } from 'https://jslib.k6.io/k6-testing/0.6.1/index.js';

export const options = {
  scenarios: {
    ui: {
      executor: 'shared-iterations',
      options: {
        browser: {
          type: 'chromium',
        },
      },
    },
  }
};

export default async function () {
  const page = await browser.newPage();
  
  // Navigate and check exact title match
  await page.goto('https://quickpizza.grafana.com/');
  await expect(page).toHaveTitle('QuickPizza');

  // Check title with regex pattern
  await expect(page).toHaveTitle(/QuickPizza/);
  await expect(page).toHaveTitle(/^Quick/);
}

RetryConfig

Mon, 21 Sep 2026 15:16:28 +0000

RetryConfig

The RetryConfig object defines configuration options that control the retry behavior of asynchronous assertions. These options can be passed to individual retrying assertions or used to create a configured expect instance with custom defaults.

Properties

Property	Type	Default	Description
timeout	number	`5000`	Maximum time to wait in milliseconds
interval	number	`100`	Time between retries in milliseconds

Description

timeout

The timeout property specifies the maximum amount of time (in milliseconds) that a retrying assertion will wait for a condition to become true before failing. If the condition is not met within this timeframe, the assertion will throw an error.

Default: 5000 (5 seconds)

interval

The interval property specifies the time (in milliseconds) between retry attempts. The assertion will check the condition, wait for the specified interval, then check again.

Default: 100 (100 milliseconds)

Usage

Per-Assertion Configuration

You can pass a RetryConfig object as the last parameter to any retrying assertion:

import { browser } from 'k6/browser';
import { expect } from 'https://jslib.k6.io/k6-testing/0.6.1/index.js';

export const options = {
  scenarios: {
    ui: {
      executor: 'shared-iterations',
      options: {
        browser: {
          type: 'chromium',
        },
      },
    },
  }
};

export default async function () {
  const page = await browser.newPage();
  await page.goto('https://quickpizza.grafana.com/');

  // Wait up to 10 seconds, checking every 500ms
  await expect(page.locator('h1')).toBeVisible({
    timeout: 10000,
    interval: 500,
  });

  // Quick check with short timeout
  await expect(page.locator('button[name="pizza-please"]')).toBeVisible({
    timeout: 1000,
    interval: 50,
  });
}

Creating a Configured Expect Instance

You can create a new expect instance with custom default configuration using expect.configure():

import { browser } from 'k6/browser';
import { expect } from 'https://jslib.k6.io/k6-testing/0.6.1/index.js';

export const options = {
  scenarios: {
    ui: {
      executor: 'shared-iterations',
      options: {
        browser: {
          type: 'chromium',
        },
      },
    },
  }
};

// Create a new expect instance with custom retry configuration
const myExpect = expect.configure({
  timeout: 10000, // 10 seconds default timeout
  interval: 200, // Check every 200ms
});

export default async function () {
  const page = await browser.newPage();
  await page.goto('https://quickpizza.grafana.com/');

  // These assertions will use the configured defaults
  await myExpect(page.locator('h1')).toBeVisible();
  await myExpect(page.locator('h1')).toHaveText('Looking to break out of your pizza routine?');

  // This assertion overrides the configured defaults
  await myExpect(page.locator('h1')).toBeVisible({
    timeout: 30000, // 30 seconds for this specific assertion
  });

  // The original expect instance is unchanged
  await expect(page.locator('button[name="pizza-please"]')).toBeVisible(); // Uses default 5000ms timeout
}

Best Practices

Choosing Appropriate Timeouts

Fast elements (1-2 seconds): Use shorter timeouts for elements that should appear quickly
Standard elements (5 seconds): Use the default timeout for most scenarios
Slow-loading content (10-30 seconds): Use longer timeouts for elements that take time to load

// Fast UI feedback - short timeout
await expect(page.locator('#validation-message')).toBeVisible({
  timeout: 2000,
});

// API-dependent content - longer timeout
await expect(page.locator('#user-profile')).toContainText('John Doe', {
  timeout: 15000,
});

// Large data sets or complex operations - very long timeout
await expect(page.locator('#report-complete')).toBeVisible({
  timeout: 60000,
  interval: 1000, // Check less frequently for long operations
});

Choosing Appropriate Intervals

Fine-grained checking (50-100ms): For rapid state changes
Standard checking (100-200ms): For most UI interactions
Coarse checking (500-1000ms): For slow operations or to reduce CPU usage

// Rapid state changes - frequent checking
await expect(page.locator('#animation')).toBeVisible({
  timeout: 5000,
  interval: 50,
});

// Standard UI interactions - default checking
await expect(page.locator('#form-submitted')).toContainText('Success');

// Slow backend operations - infrequent checking
await expect(page.locator('#batch-job-status')).toContainText('Complete', {
  timeout: 300000, // 5 minutes
  interval: 5000, // Check every 5 seconds
});