Menu
Documentationbreadcrumb arrow Grafana k6breadcrumb arrow JavaScript APIbreadcrumb arrow jslibbreadcrumb arrow testingbreadcrumb arrow Retrying Assertions
Open source

Retrying Assertions

Retrying assertions are asynchronous assertions that automatically retry until a condition becomes true or a timeout is reached. They are particularly useful for browser testing where elements may not be immediately available or when testing dynamic content that changes over time.

Overview

Retrying assertions differ from non-retrying assertions in that they:

  • Automatically retry - They continuously check the condition until it passes or times out
  • Are asynchronous - They return promises and must be await-ed
  • Have configurable timeouts - You can set custom timeout and polling intervals
  • Are ideal for dynamic content - Perfect for testing UI elements that appear/disappear or change over time

When to Use Retrying Assertions

Retrying assertions are best suited for:

  • Browser testing - Checking element visibility, text content, or state changes
  • Dynamic content - Testing content that loads asynchronously
  • User interactions - Verifying UI changes after clicks, form submissions, etc.
  • Loading states - Waiting for spinners to disappear or content to appear
  • API polling - Waiting for external systems to reach expected states

Usage

All retrying assertions must be awaited since they return promises:

JavaScript 
import { browser } from 'k6/browser';
import { expect } from 'https://jslib.k6.io/k6-testing/0.5.0/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 become visible
  await expect(page.locator('h1')).toBeVisible();

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

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

Configuration

You can configure timeout and polling behavior by creating a configured expect instance or per assertion:

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

// Create configured expect instance
const slowExpect = expect.configure({
  timeout: 10000, // 10 seconds timeout
  interval: 200, // Check every 200ms
});

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

  // Use configured timeout
  await slowExpect(page.locator('h1')).toBeVisible();

  // Override timeout for specific assertion
  await slowExpect(page.locator('button[name="pizza-please"]')).toBeVisible({
    timeout: 30000,
  });

  // Original expect instance still available with defaults
  await expect(page.locator('h1')).toBeVisible();
}

Available Retrying Assertions

MethodDescription
toBeVisible()Element is visible on the page
toBeHidden()Element is hidden or not visible
toBeEnabled()Element is enabled and interactive
toBeDisabled()Element is disabled
toBeChecked()Checkbox or radio button is checked
toBeEditable()Element is editable
toHaveText()Element has specific text content
toContainText()Element contains specific text
toHaveValue()Input element has specific value
toHaveAttribute()Element has specific attribute value