@testdriverai/agent 7.11.229-canary → 7.11.232-test

package/docs/type.mdx

@@ -1,358 +1,110 @@
 ---
 title: "type()"
 sidebarTitle: "type"
-description: "Type text into focused input fields"
+description: "Type text into the field that has keyboard focus, with optional masking for secrets."
 icon: "keyboard"
 ---
 
-## Overview
+Type text into whatever has keyboard focus. Click the field first:
 
-Type text or numbers into the input field that has focus. You can set an optional delay between the keystrokes.
+```javascript
+await testdriver.find('Email input field').click();
+await testdriver.type('user@example.com');
+```
 
-## Syntax
+`type()` is a client method. Elements don't have a `type()` method.
 
-```javascript
-await testdriver.type(text, options)
+## Signature
+
+```typescript
+testdriver.type(text: string | number, options?: { secret?: boolean }): Promise<void>
 ```
 
 ## Parameters
 
 <ParamField path="text" type="string | number" required>
-  Text to type (can be a string or number)
+  The text to type. Numbers are converted to strings.
 </ParamField>
 
-<ParamField path="options" type="object | number">
-  Typing options (or legacy delay number)
-  
+<ParamField path="options" type="object">
   <Expandable title="properties">
-    <ParamField path="delay" type="number" default={250}>
-      Delay between keystrokes in milliseconds
-    </ParamField>
-    
-    <ParamField path="secret" type="boolean" default={false}>
-      If `true`, TestDriver makes the text sensitive data. It does not log or store it in the debug info or in dashcam.
+    <ParamField path="secret" type="boolean" default="false">
+      Keep the text out of TestDriver's logs and test results. They show `****` instead. Use it for passwords, tokens and other sensitive values.
     </ParamField>
   </Expandable>
 </ParamField>
 
-## Returns
-
-`Promise<void>`
-
-## Examples
-
-### Basic Typing
-
-```javascript
-// Type text
-await testdriver.type('hello@example.com');
-
-// Type numbers
-await testdriver.type(12345);
-
-// Type with custom delay (legacy syntax)
-await testdriver.type('slow typing', 500); // 500ms between each character
-
-// Type with options object
-await testdriver.type('text', { delay: 500 });
-```
-
-### Password/Secret Handling
-
-```javascript
-// ✅ SECURE - Mark as secret to prevent logging
-const passwordField = await testdriver.find('password input');
-await passwordField.click();
-await testdriver.type('MySecureP@ssw0rd', { secret: true });
-// Password NOT logged in dashcam or debug output
-
-// ❌ INSECURE - Password will be logged
-await testdriver.type('MySecureP@ssw0rd');
-// Password appears in logs, dashcam replay, and debug info
-
-// Use secret for any sensitive data
-await testdriver.find('api key input').click();
-await testdriver.type('sk-1234567890abcdef', { secret: true });
-
-await testdriver.find('credit card input').click();
-await testdriver.type('4111111111111111', { secret: true });
-```
-
 <Warning>
-  **Always use `secret: true` for passwords and sensitive data.**
-  
-  If you do not use this option, the typed text shows in these:
-  - Dashcam video replays
-  - TestDriver logs
-  - Debug screenshots
-  - Error messages
+  `secret: true` doesn't hide what appears on screen. If the field shows its contents, the text is visible in the Dashcam recording.
 </Warning>
 
-### Form Filling
+## Errors
 
-```javascript
-// Focus field and type
-const emailField = await testdriver.find('email input');
-await emailField.click();
-await testdriver.type('user@example.com');
+Throws an error if `text` is `undefined` or `null`. This usually means an environment variable isn't set.
 
-// Tab to next field and type
-await testdriver.pressKeys(['tab']);
-await testdriver.type('John Doe');
+## Examples
 
-// Type password securely
-await testdriver.pressKeys(['tab']);
-await testdriver.type('MySecureP@ssw0rd', { secret: true });
-```
+### Type a password
 
-### Clearing and Replacing Text
+Read secrets from environment variables, not from your test code. See [Secrets](/secrets).
 
 ```javascript
-const searchBox = await testdriver.find('search input');
-await searchBox.click();
-
-// Clear existing text
-await testdriver.pressKeys(['ctrl', 'a']); // Select all
-await testdriver.type('new search query');
+await testdriver.find('Password input field').click();
+await testdriver.type(process.env.TD_PASSWORD, { secret: true });
 ```
 
-## Best Practices
-
-<Check>
-  **Focus the field first**
-  
-  Always click the input field or navigate to it before typing:
-  
-  ```javascript
-  const input = await testdriver.find('username input');
-  await input.click();
-  await testdriver.type('testuser');
-  ```
-</Check>
+### Replace the text in a field
 
-<Check>
-  **Use Tab for navigation**
-  
-  Navigate between fields using Tab instead of clicking each one:
-  
-  ```javascript
-  const firstField = await testdriver.find('first name');
-  await firstField.click();
-  await testdriver.type('John');
-  
-  await testdriver.pressKeys(['tab']);
-  await testdriver.type('Doe');
-  
-  await testdriver.pressKeys(['tab']);
-  await testdriver.type('john@example.com');
-  ```
-</Check>
-
-<Check>
-  **Clear fields before typing**
-  
-  Clear existing content to avoid appending:
-  
-  ```javascript
-  const input = await testdriver.find('search field');
-  await input.click();
-  await testdriver.pressKeys(['ctrl', 'a']); // Select all
-  await testdriver.type('new search');
-  ```
-</Check>
-
-<Warning>
-  **Field must be focused**
-  
-  Typing will only work if an input field is currently focused. If no field is focused, the text may be lost or trigger unexpected keyboard shortcuts.
-</Warning>
-
-## Use Cases
-
-<AccordionGroup>
-  <Accordion title="Login Forms">
-    ```javascript
-    await testdriver.focusApplication('Google Chrome');
-    
-    const usernameField = await testdriver.find('username input');
-    await usernameField.click();
-    await testdriver.type('testuser@example.com');
-    
-    await testdriver.pressKeys(['tab']);
-    await testdriver.type('MyP@ssword123', { secret: true });
-    
-    await testdriver.pressKeys(['enter']);
-    ```
-  </Accordion>
-  
-  <Accordion title="Search Fields">
-    ```javascript
-    const searchBox = await testdriver.find('search input');
-    await searchBox.click();
-    await testdriver.type('laptop computers');
-    await testdriver.pressKeys(['enter']);
-    
-    // Wait for results
-    await new Promise(r => setTimeout(r, 2000));
-    ```
-  </Accordion>
-  
-  <Accordion title="Multi-Field Forms">
-    ```javascript
-    // First field
-    const nameField = await testdriver.find('full name input');
-    await nameField.click();
-    await testdriver.type('Jane Smith');
-    
-    // Navigate with Tab
-    await testdriver.pressKeys(['tab']);
-    await testdriver.type('jane.smith@example.com');
-    
-    await testdriver.pressKeys(['tab']);
-    await testdriver.type('+1-555-0123');
-    
-    await testdriver.pressKeys(['tab']);
-    await testdriver.type('123 Main Street');
-    ```
-  </Accordion>
-  
-  <Accordion title="Text Editors">
-    ```javascript
-    const editor = await testdriver.find('text editor area');
-    await editor.click();
-    
-    await testdriver.type('# My Document', 100);
-    await testdriver.pressKeys(['enter', 'enter']);
-    await testdriver.type('This is the first paragraph.', 50);
-    ```
-  </Accordion>
-  
-  <Accordion title="Numeric Input">
-    ```javascript
-    const quantityField = await testdriver.find('quantity input');
-    await quantityField.click();
-    
-    // Clear field
-    await testdriver.pressKeys(['ctrl', 'a']);
-    
-    // Type number
-    await testdriver.type(5);
-    ```
-  </Accordion>
-</AccordionGroup>
-
-## Typing Speed
-
-Adjust the delay parameter based on your needs:
+`type()` adds to what's already in the field. Select the old text first to replace it:
 
 ```javascript
-// Fast typing (100ms delay)
-await testdriver.type('quick entry', 100);
-
-// Normal typing (250ms - default)
-await testdriver.type('standard speed');
-
-// Slow typing (500ms delay) - useful for fields with live validation
-await testdriver.type('slow and steady', 500);
-
-// Very slow (1000ms delay) - for problematic fields
-await testdriver.type('one by one', 1000);
+await testdriver.find('Search input').click();
+await testdriver.pressKeys(['ctrl', 'a']);
+await testdriver.type('wireless headphones');
 ```
 
-<Note>
-  Some applications with live validation or autocomplete may require slower typing speeds to avoid race conditions.
-</Note>
+### Type several lines
 
-## Special Characters
+`type()` doesn't press Enter for you. Use [`pressKeys()`](/press-keys) between lines:
 
 ```javascript
-// Email addresses
-await testdriver.type('user@example.com');
-
-// URLs
-await testdriver.type('https://example.com/path?query=value');
-
-// Passwords with special characters
-await testdriver.type('P@ssw0rd!#$%');
-
-// Paths
-await testdriver.type('C:\\Users\\Documents\\file.txt');
-
-// Multi-line text (use pressKeys for Enter)
-await testdriver.type('Line 1');
+await testdriver.find('Comment text area').click();
+await testdriver.type('First line');
 await testdriver.pressKeys(['enter']);
-await testdriver.type('Line 2');
+await testdriver.type('Second line');
 ```
 
-## Complete Example
+## Complete example
 
-```javascript
-import { beforeAll, afterAll, describe, it, expect } from 'vitest';
-import TestDriver from 'testdriverai';
+```javascript tests/login.test.mjs
+import { describe, expect, it } from 'vitest';
+import { TestDriver } from 'testdriverai/vitest/hooks';
 
-describe('Form Filling with Type', () => {
-  let testdriver;
+describe('Login', () => {
+  it('signs in with a username and password', async (context) => {
+    const testdriver = TestDriver(context);
+    await testdriver.provision.chrome({ url: 'https://testdriver-sandbox.vercel.app/login' });
 
-  beforeAll(async () => {
-    client = new TestDriver(process.env.TD_API_KEY);
-    await testdriver.auth();
-    await testdriver.connect();
-  });
+    // The sandbox login page shows its test password on screen
+    const password = await testdriver.extract('the password');
 
-  afterAll(async () => {
-    await testdriver.disconnect();
-  });
+    await testdriver.find('Username input field').click();
+    await testdriver.type('standard_user');
 
-  it('should fill out registration form', async () => {
-    await testdriver.focusApplication('Google Chrome');
-    
-    // Email field
-    const emailField = await testdriver.find('email input field');
-    await emailField.click();
-    await testdriver.type('john.doe@example.com');
-    
-    // Tab through form fields
-    await testdriver.pressKeys(['tab']);
-    await testdriver.type('John');
-    
-    await testdriver.pressKeys(['tab']);
-    await testdriver.type('Doe');
-    
-    await testdriver.pressKeys(['tab']);
-    await testdriver.type('MySecureP@ssword123');
-    
-    await testdriver.pressKeys(['tab']);
-    await testdriver.type('MySecureP@ssword123'); // Confirm password
-    
-    // Verify fields were filled
-    const result = await testdriver.assert('all form fields are filled');
-    expect(result).toBeTruthy();
-  });
+    await testdriver.find('Password input field').click();
+    await testdriver.type(password, { secret: true });
+
+    await testdriver.find('Sign in button below the password field').click();
 
-  it('should update search query', async () => {
-    const searchBox = await testdriver.find('search input');
-    await searchBox.click();
-    
-    // Type initial search
-    await testdriver.type('laptops');
-    await testdriver.pressKeys(['enter']);
-    
-    await new Promise(r => setTimeout(r, 2000));
-    
-    // Update search
-    await searchBox.click();
-    await testdriver.pressKeys(['ctrl', 'a']); // Select all
-    await testdriver.type('gaming laptops');
-    await testdriver.pressKeys(['enter']);
-    
-    // Verify new search
-    await testdriver.assert('search results for "gaming laptops" are shown');
+    const result = await testdriver.assert('the product list is shown');
+    expect(result).toBe(true);
   });
 });
 ```
 
-## Related Methods
+## Related
 
-- [`pressKeys()`](/press-keys) - Press keyboard keys and shortcuts
-- [`find()`](/find) - Locate input fields
-- [`click()`](/click) - Focus input fields
+- [pressKeys()](/press-keys): press Enter, Tab and shortcuts
+- [click()](/click): focus a field before you type
+- [Secrets](/secrets): keep credentials out of your test code
+- [Perform actions](/performing-actions): every kind of action in one guide

package/docs/variables.mdx

@@ -1,111 +1,151 @@
 ---
-title: "Using Variables"
-description: "Use dynamic data and secure secrets in your tests"
+title: "Use variables and test data"
+sidebarTitle: "Using variables"
+description: "Drive tests with environment variables, shared fixtures, and generated data."
 icon: "square-root-variable"
 ---
 
-Make your tests larger with dynamic data and secure secrets. Select the correct method for your test needs.
+Keep the values your tests type and visit out of the test code. There are three common sources:
 
-## Environment Variables
+- **Environment variables** for settings that change between environments, such as the app URL.
+- **Fixtures** for a known set of test data you reuse across tests.
+- **Generated data** for values that must be unique on every run.
 
-Use environment variables for **configuration that changes between environments** (dev, staging, production). Also use them for **secrets that you must not commit to the code**. Use this method when you must run the same tests against different servers or with different credentials.
+To keep passwords and tokens out of logs as well, see [Use secrets](/secrets).
 
-```javascript
-import { test } from 'vitest';
-import { chrome } from 'testdriverai/presets';
-
-test('multi-environment testing', async (context) => {
-  const env = process.env.TEST_ENV || 'staging';
-  const urls = {
-    dev: 'https://dev.myapp.com',
-    staging: 'https://staging.myapp.com',
-    production: 'https://myapp.com'
-  };
-
-  const { testdriver } = await chrome(context, { 
-    url: urls[env] 
-  });
-
-  await testdriver.assert('app is running');
+## Read environment variables
+
+Read settings from `process.env` so the same test runs against dev, staging, or production.
+
+```javascript tests/home.test.mjs
+import { expect, it } from 'vitest';
+import { TestDriver } from 'testdriverai/vitest/hooks';
+
+const appUrl = process.env.APP_URL ?? 'https://testdriver-sandbox.vercel.app';
+
+it('shows the login form', async (context) => {
+  const testdriver = TestDriver(context);
+  await testdriver.provision.chrome({ url: `${appUrl}/login` });
+
+  const result = await testdriver.assert('a login form is visible');
+  expect(result).toBe(true);
 });
 ```
 
+Set the variable when you run the tests:
+
 ```bash
-# Run against different environments
-TEST_ENV=dev vitest run
-TEST_ENV=staging vitest run
-TEST_ENV=production vitest run
+APP_URL=https://staging.example.com npx vitest run
 ```
 
-## Test Fixtures
+TestDriver loads a `.env` file in your project root automatically, so you can also keep local values there:
 
-Test fixtures work best when you have **structured, reusable test data** that needs to be shared across multiple tests. Use fixtures when testing different user roles, product catalogs, or any scenario where you want to parameterize tests with a known set of data.
+```bash .env
+APP_URL=https://staging.example.com
+```
 
-```javascript test/fixtures/users.js
-export const testUsers = [
-  { email: 'admin@test.com', role: 'admin' },
-  { email: 'user@test.com', role: 'user' },
-  { email: 'guest@test.com', role: 'guest' }
-];
+## Reuse test data with fixtures
 
-export const products = [
-  { name: 'Laptop', price: 999 },
-  { name: 'Mouse', price: 29 },
-  { name: 'Keyboard', price: 89 }
+Put shared test data in its own module and import it wherever you need it.
+
+```javascript tests/fixtures/usernames.js
+export const usernames = [
+  { label: 'a typical username', value: 'standard_user' },
+  { label: 'a username with a dot', value: 'jane.doe' },
+  { label: 'a 32-character username', value: 'user_with_a_32_character_name_01' },
 ];
 ```
 
-```javascript test/permissions.test.js
-import { test } from 'vitest';
-import { chrome } from 'testdriverai/presets';
-import { testUsers } from './fixtures/users.js';
-
-test.each(testUsers)('$role can access dashboard', async ({ email, role }, context) => {
-  const { testdriver } = await chrome(context, { url });
-  
-  await testdriver.find('email input').type(email);
-  await testdriver.find('password input').type('password123');
-  await testdriver.find('login button').click();
-  
-  if (role === 'admin') {
-    await testdriver.assert('admin panel is visible');
-  } else {
-    await testdriver.assert('user dashboard is visible');
-  }
+Use Vitest's `it.for()` to run the same test once per fixture. Unlike `it.each()`, `it.for()` passes the test `context` as the second argument, which `TestDriver(context)` needs.
+
+```javascript tests/login.test.mjs
+import { expect, it } from 'vitest';
+import { TestDriver } from 'testdriverai/vitest/hooks';
+import { usernames } from './fixtures/usernames.js';
+
+it.for(usernames)('accepts $label', async (username, context) => {
+  const testdriver = TestDriver(context);
+  await testdriver.provision.chrome({ url: 'https://testdriver-sandbox.vercel.app/login' });
+
+  const usernameField = await testdriver.find('Username input field');
+  await usernameField.click();
+  await testdriver.type(username.value);
+
+  const result = await testdriver.assert(`the username field contains "${username.value}"`);
+  expect(result).toBe(true);
 });
 ```
 
-## Dynamic Data Generation
+Each fixture becomes its own test with its own sandbox.
 
-Dynamic data generation is perfect for **creating unique test data on each run**, avoiding conflicts with existing records, and **testing edge cases with realistic data**. Use libraries like Faker when you need fresh emails, names, or other data that won't collide with previous test runs.
+## Generate unique data
 
-```javascript
-import { test } from 'vitest';
-import { chrome } from 'testdriverai/presets';
+When a test creates records, such as new accounts, generate fresh values on every run so they don't collide with earlier runs. [Faker](https://fakerjs.dev) is a common choice:
+
+```bash
+npm install --save-dev @faker-js/faker
+```
+
+```javascript tests/signup.test.mjs
 import { faker } from '@faker-js/faker';
+import { expect, it } from 'vitest';
+import { TestDriver } from 'testdriverai/vitest/hooks';
+
+it('creates an account', async (context) => {
+  const testdriver = TestDriver(context);
+  await testdriver.provision.chrome({ url: `${process.env.APP_URL}/signup` });
+
+  const email = faker.internet.email();
+
+  const emailField = await testdriver.find('Email input field');
+  await emailField.click();
+  await testdriver.type(email);
 
-test('user registration with dynamic data', async (context) => {
-  const { testdriver } = await chrome(context, { url });
-
-  // Generate unique test data for each run
-  const userData = {
-    firstName: faker.person.firstName(),
-    lastName: faker.person.lastName(),
-    email: faker.internet.email(),
-    password: faker.internet.password({ length: 12 })
-  };
-
-  await testdriver.find('first name input').type(userData.firstName);
-  await testdriver.find('last name input').type(userData.lastName);
-  await testdriver.find('email input').type(userData.email);
-  await testdriver.find('password input').type(userData.password);
-  await testdriver.find('register button').click();
-
-  await testdriver.assert('registration successful');
-  console.log('Registered user:', userData.email);
+  const passwordField = await testdriver.find('Password input field');
+  await passwordField.click();
+  await testdriver.type(faker.internet.password({ length: 12 }), { secret: true });
+
+  const createAccountButton = await testdriver.find('Create account button below the form');
+  await createAccountButton.click();
+
+  const result = await testdriver.assert('a welcome message is visible');
+  expect(result).toBe(true);
 });
 ```
 
-```bash
-npm install --save-dev @faker-js/faker
+## Keep values out of descriptions
+
+Pass changing values to [`type()`](/type), not to [`find()`](/find).
+
+The [cache](/caching) matches `find()` descriptions exactly. A description that contains a generated value misses the cache on every run:
+
+```javascript
+// Misses the cache whenever the email changes
+const emailField = await testdriver.find(`input next to ${email}`);
 ```
+
+Describe the element itself, and type the value after you click it:
+
+```javascript
+// Same description every run, so it can be cached
+const emailField = await testdriver.find('Email input field');
+await emailField.click();
+await testdriver.type(email);
+```
+
+## Next steps
+
+<CardGroup cols={2}>
+  <Card title="Use secrets" icon="key" href="/secrets">
+    Keep passwords and tokens out of code and logs.
+  </Card>
+  <Card title="Reuse code" icon="recycle" href="/reusable-code">
+    Share helpers like a login step across tests.
+  </Card>
+  <Card title="Run in CI/CD" icon="code-branch" href="/ci-cd">
+    Pass environment variables to tests in your pipeline.
+  </Card>
+  <Card title="Caching" icon="brain" href="/caching">
+    Write descriptions that reuse cached locations.
+  </Card>
+</CardGroup>