@testdriverai/agent 7.11.229-canary → 7.11.231-test

package/docs/extract.mdx

@@ -1,225 +1,124 @@
 ---
 title: "extract()"
 sidebarTitle: "extract"
-description: "Read information from the screen using AI and return it as a string"
+description: "Read a value off the screen with AI and get it back as a string."
 icon: "wand-magic-sparkles"
 ---
 
-## Overview
+Read a value off the screen, such as an order number or a price. Describe what you want, and the AI returns it as a string.
 
-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.
+```javascript
+const orderNumber = await testdriver.extract('the order confirmation number');
+```
 
-[`assert()`](/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.
+[`assert()`](/assert) tells you whether something is true. `extract()` gives you the value itself, so you can compare it, log it, or type it somewhere else.
 
-## Syntax
+## Signature
 
-```javascript
-const value = await testdriver.extract(description)
-const value = await testdriver.extract({ description })
+```typescript
+testdriver.extract(description: string): Promise<string>
+testdriver.extract(options: { description: string }): Promise<string>
 ```
 
+Both forms do the same thing.
+
 ## Parameters
 
 <ParamField path="description" type="string" required>
-  A natural language description of the information to read from the screen.
+  What to read from the screen, such as `'the total price in the order summary'`. Say what format you want, too: `'the cart total as a number, without the dollar sign'`.
 </ParamField>
 
-<Info>
-  `extract()` also accepts an options object, `extract({ description })`. This is the same as the positional form. The string form is the most common.
-</Info>
-
 ## 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.
+`Promise<string>`. The value the AI read, with no extra text. Convert it yourself when you need a number or another type.
 
-## Examples
-
-### Basic Extraction
+## Errors
 
-```javascript
-// Read text content
-const title = await testdriver.extract('the page title');
-const heading = await testdriver.extract('the main heading text');
+`extract()` throws if the AI service fails, for example when it's temporarily unavailable.
 
-// 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');
+It doesn't throw when the value isn't on screen. Check the result before you rely on it.
 
-// Read status and confirmation values
-const status = await testdriver.extract('the order status');
-const orderNumber = await testdriver.extract('the order confirmation number');
-```
+## Examples
 
-### Using the Extracted Value
+### Compare a value with expect()
 
 ```javascript
-// 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:
-
-  ```javascript
-  // ❌ 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:
+### Read a number
 
-  ```javascript
-  // 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:
-
-  ```javascript
-  const confirmation = await testdriver.extract('the confirmation number');
-  expect(confirmation).toMatch(/^ORD-\d{6}$/);
-  ```
-</Check>
-
-## Use Cases
-
-<AccordionGroup>
-  <Accordion title="Capturing Confirmation Details">
-    ```javascript
-    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');
+```javascript
+const total = await testdriver.extract('the cart total as a number, without the dollar sign');
+expect(Number(total)).toBeGreaterThan(0);
+```
 
-    console.log(`Order ${orderNumber} arrives ${eta}`);
-    ```
-  </Accordion>
+### Check the format of a generated value
 
-  <Accordion title="Reading Tooltip and Hover Content">
-    ```javascript
-    const icon = await testdriver.find('info icon next to the price');
-    await icon.hover();
+```javascript
+const confirmation = await testdriver.extract('the confirmation number');
+expect(confirmation).toMatch(/^ORD-\d{6}$/);
+```
 
-    const tooltipText = await testdriver.extract('the tooltip text');
-    expect(tooltipText).toContain('tax included');
-    ```
-  </Accordion>
+### Pass a value to the next step
 
-  <Accordion title="Verifying Dynamic Values">
-    ```javascript
-    // Read a value before an action
-    const before = await testdriver.extract('the account balance');
+```javascript
+const resetCode = await testdriver.extract('the password reset code');
 
-    const addBtn = await testdriver.find('add funds button');
-    await addBtn.click();
+await testdriver.find('Reset code input field').click();
+await testdriver.type(resetCode);
+```
 
-    // 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>
+### Read text that appears on hover
 
-  <Accordion title="Passing Data Between Steps">
-    ```javascript
-    // Read a generated code on one screen...
-    const resetCode = await testdriver.extract('the password reset code');
+```javascript
+await testdriver.find('info icon next to the price').hover();
 
-    // ...and type it into the next
-    const codeField = await testdriver.find('reset code input');
-    await codeField.click();
-    await testdriver.type(resetCode);
-    ```
-  </Accordion>
-</AccordionGroup>
+const tooltip = await testdriver.extract('the tooltip text');
+expect(tooltip).toContain('tax included');
+```
 
-## Complete Example
+## How it works
 
-```javascript
-import { beforeAll, afterAll, describe, it, expect } from 'vitest';
-import TestDriver from 'testdriverai';
+1. TestDriver takes a screenshot of the sandbox.
+2. It sends the screenshot and your description to the AI.
+3. The AI returns only the value you asked for.
 
-describe('Extraction', () => {
-  let testdriver;
+Results aren't cached. Every call reads the current screen.
 
-  beforeAll(async () => {
-    testdriver = new TestDriver(process.env.TD_API_KEY);
-    await testdriver.auth();
-    await testdriver.connect();
-  });
+## Complete example
 
-  afterAll(async () => {
-    await testdriver.disconnect();
-  });
+```javascript tests/login.test.mjs
+import { describe, expect, it } from 'vitest';
+import { TestDriver } from 'testdriverai/vitest/hooks';
 
-  it('should capture the order confirmation', async () => {
-    await testdriver.focusApplication('Google Chrome');
+describe('Login', () => {
+  it('signs in with the password shown on the page', async (context) => {
+    const testdriver = TestDriver(context);
+    await testdriver.provision.chrome({ url: 'https://testdriver-sandbox.vercel.app/login' });
 
-    // Complete a checkout
-    const checkoutBtn = await testdriver.find('checkout button');
-    await checkoutBtn.click();
+    // The sandbox login page shows its test password on screen
+    const password = await testdriver.extract('the password');
+    expect(password).not.toBe('');
 
-    const placeOrderBtn = await testdriver.find('place order button');
-    await placeOrderBtn.click();
+    await testdriver.find('Username input field').click();
+    await testdriver.type('standard_user');
 
-    // Verify we reached confirmation
-    await testdriver.assert('the order confirmation page is displayed');
+    await testdriver.find('Password input field').click();
+    await testdriver.type(password, { secret: true });
 
-    // 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');
+    await testdriver.find('Sign in button below the password field').click();
 
-    // Assert on the extracted values
-    expect(orderNumber).toBeTruthy();
-    expect(Number(total)).toBeGreaterThan(0);
+    const result = await testdriver.assert('the product list is shown');
+    expect(result).toBe(true);
   });
 });
 ```
 
-## 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
-
-<Note>
-  Like [assertions](/making-assertions), `extract()` reads the screen fresh on every call — it is not cached — so it always reflects the current state of the app.
-</Note>
-
-## Related Methods
+## Related
 
-- [`assert()`](/assert) - Verify screen state with a boolean AI judgment
-- [`find()`](/find) - Locate elements to interact with
-- [`parse()`](/parse) - Detect all UI elements on screen
+- [assert()](/assert): check a statement about the screen
+- [Make assertions](/making-assertions): choose between `assert()` and `extract()`
+- [find()](/find): locate an element to act on
+- [parse()](/parse): list every element on screen