Testdriver:Extract

Overview

Get information from the screen with AI. TestDriver returns it as a string. Describe what you want in natural language. The AI reads the screen and returns the correct value: text, numbers, labels, status messages, or other content on the screen.

assert() returns a boolean result. But extract() returns the real value. Thus you can store it, compare it, or use it in later steps and in framework assertions.

Syntax

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

Parameters

Returns

Promise<string> — The information from the screen. TestDriver returns the value as text. Parse it or cast it yourself if you need a number or another type.

Examples

Basic Extraction

javascriptCopy code
// 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

javascriptCopy code
// 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

Precise descriptions produce cleaner values:

javascriptCopy code
// ❌ 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');

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

javascriptCopy code
// 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');

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

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

Use Cases

Copy code
// 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}`);
```

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

Copy code
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, ''))
);
```

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

Complete Example

javascriptCopy code
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 testdriver.assert('the order confirmation page is displayed');

    // Extract the details the app generated
    const orderNumber = await testdriver.extract('the order confirmation number');
    const total = await testdriver.extract('the order total as a number without currency symbol');

    // Assert on the extracted values
    expect(orderNumber).toBeTruthy();
    expect(Number(total)).toBeGreaterThan(0);
  });
});

How It Works

1. TestDriver captures a screenshot of the current screen
2. The image and your description are sent to the TestDriver API
3. The AI reads the requested information from the screenshot
4. The extracted value is returned as a string

Related Methods

• assert() - Verify screen state with a boolean AI judgment
• find() - Locate elements to interact with
• parse() - Detect all UI elements on screen