/testdriver-extract

name: testdriver:extract
description: Read information from the screen using AI and return it as a string

<!-- Generated from extract.mdx. DO NOT EDIT. -->

Overview

Extract information from the current screen using AI and return it as a string. Describe what you want in natural language, and the AI reads the screen and returns the matching value — text, numbers, labels, status messages, or any other on-screen content.

Unlike [`assert()`](/assert), which returns a boolean verdict, `extract()` returns the actual value so you can store it, compare it, or feed it into later steps and framework assertions.

Syntax

const value = await testdriver.extract(description)
const value = await testdriver.extract({ description })

Parameters

<ParamField path="description" type="string" required> Natural language description of the information to read from the screen. </ParamField>

<Info> `extract()` also accepts an options object — `extract({ description })` — which is equivalent to the positional form. The bare string form is the most common. </Info>

Returns

`Promise<string>` — The information read from the screen. Returns the extracted value as text; parse or cast it yourself if you need a number or other type.

Examples

Basic Extraction

// Read text content
const title = await testdriver.extract('the page title');
const heading = await testdriver.extract('the main heading text');

// Read numbers and prices
const price = await testdriver.extract('the total price shown in the cart');
const count = await testdriver.extract('the number of items in the list');

// Read status and confirmation values
const status = await testdriver.extract('the order status');
const orderNumber = await testdriver.extract('the order confirmation number');

Using the Extracted Value

// Store and reuse across steps
const orderNumber = await testdriver.extract('the order confirmation number');
console.log('Order:', orderNumber);

// Combine with framework assertions
import { expect } from 'vitest';

const message = await testdriver.extract('the success message text');
expect(message).toContain('successfully');

// Cast to a number when you need to compare
const totalText = await testdriver.extract('the cart total as a number without currency symbol');
expect(Number(totalText)).toBeGreaterThan(0);

Best Practices

<Check> **Be specific about what to read**

Precise descriptions produce cleaner values:

  // ❌ Too vague — may return extra surrounding text
  const price = await testdriver.extract('price');

  // ✅ Specific — targets a single value
  const price = await testdriver.extract('the total price in the order summary, digits only');

</Check>

<Check> **Ask for the format you want**

Steer the output by describing the desired shape in the prompt:

  // Strip currency symbols
  const total = await testdriver.extract('the order total as a number without the dollar sign');

  // Isolate a single field
  const email = await testdriver.extract('the email address shown in the profile header');

</Check>

<Check> **Extract for detailed assertions**

Use `extract()` when a boolean [`assert()`](/assert) isn't enough and you need the actual value to inspect:

  const confirmation = await testdriver.extract('the confirmation number');
  expect(confirmation).toMatch(/^ORD-\d{6}$/);

</Check>

Use Cases

<AccordionGroup> <Accordion title="Capturing Confirmation Details">

    const submitBtn = await testdriver.find('place order button');
    await submitBtn.click();

    // Read the confirmation the app generated
    const orderNumber = await testdriver.extract('the order confirmation number');
    const eta = await testdriver.extract('the estimated delivery date');

    console.log(`Order ${orderNumber} arrives ${eta}`);

</Accordion>

<Accordion title="Reading Tooltip and Hover Content">

    const icon = await testdriver.find('info icon next to the price');
    await icon.hover();

    const tooltipText = await testdriver.extract('the tooltip text');
    expect(tooltipText).toContain('tax included');

</Accordion>

<Accordion title="Verifying Dynamic Values">

    // Read a value before an action
    const before = await testdriver.extract('the account balance');

    const addBtn = await testdriver.find('add funds button');
    await addBtn.click();

    // Read it again after and compare
    const after = await testdriver.extract('the account balance');
    expect(Number(after.replace(/[^0-9.]/g, ''))).toBeGreaterThan(
      Number(before.replace(/[^0-9.]/g, ''))
    );

</Accordion>

<Accordion title="Passing Data Between Steps">

    // Read a generated code on one screen...
    const resetCode = await testdriver.extract('the password reset code');

    // ...and type it into the next
    const codeField = await testdriver.find('reset code input');
    await codeField.click();
    await testdriver.type(resetCode);

</Accordion> </AccordionGroup>

Complete Example

import { beforeAll, afterAll, describe, it, expect } from 'vitest';
import TestDriver from 'testdriverai';

describe('Extraction', () => {
  let testdriver;

  beforeAll(async () => {
    testdriver = new TestDriver(process.env.TD_API_KEY);
    await testdriver.auth();
    await testdriver.connect();
  });

  afterAll(async () => {
    await testdriver.disconnect();
  });

  it('should capture the order confirmation', async () => {
    await testdriver.focusApplication('Google Chrome');

    // Complete a checkout
    const checkoutBtn = await testdriver.find('checkout button');
    await checkoutBtn.click();

    const placeOrderBtn = await testdriver.find('place order button');
    await placeOrderBtn.click();

    // Verify we reached confirmation
    await t