testdriver:ai

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

## Overview

The `ai()` method allows you to execute complex tasks using natural language descriptions. TestDriver's AI will figure out the steps needed to accomplish the task.

## Syntax

```javascript
await testdriver.ai(task, options)
```

## Parameters

<ParamField path="task" type="string" required>
  Natural language description of what to do
</ParamField>

<ParamField path="options" type="object">
  Execution options
  
  <Expandable title="properties">
    <ParamField path="validateAndLoop" type="boolean" default="false">
      Whether to validate completion and retry if incomplete
    </ParamField>
  </Expandable>
</ParamField>

## Returns

`Promise<string | void>` - Final AI response if `validateAndLoop` is true

## Examples

### Basic Usage

```javascript
// Simple task execution
await testdriver.ai('Click the submit button');

// Complex multi-step task
await testdriver.ai('Fill out the contact form and submit it');

// Navigation task
await testdriver.ai('Go to the settings page and enable notifications');
```

### With Validation

```javascript
// AI will verify the task completed successfully
const result = await testdriver.ai('Complete the checkout process', { 
  validateAndLoop: true 
});

console.log('Task result:', result);
```

### Multi-Step Workflows

```javascript
// The AI will break down complex tasks
await testdriver.ai('Search for "laptop", add the first result to cart, and proceed to checkout');

// UI exploration
await testdriver.ai('Find and click all menu items to explore the application');
```

## Use Cases

<AccordionGroup>
  <Accordion title="Exploratory Testing">
    Use AI to explore unfamiliar applications:
    
    ```javascript
    await testdriver.ai('Explore the main navigation menu');
    await testdriver.ai('Try to find the user profile settings');
    ```
  </Accordion>
  
  <Accordion title="Complex Workflows">
    Let AI handle multi-step processes:
    
    ```javascript
    await testdriver.ai('Complete the multi-step registration form');
    await testdriver.ai('Configure all the advanced settings to default values');
    ```
  </Accordion>
  
  <Accordion title="Flexible Interactions">
    When exact element locations aren't critical:
    
    ```javascript
    await testdriver.ai('Close any popup dialogs');
    await testdriver.ai('Accept the cookie consent if it appears');
    ```
  </Accordion>
</AccordionGroup>

## Best Practices

<Check>
  **Be specific but flexible**: Give enough context without over-constraining the AI
  
  ```javascript
  // ✅ Good
  await testdriver.ai('Add the first product to the shopping cart');
  
  // ❌ Too vague
  await testdriver.ai('do something');
  
  // ❌ Too specific (defeats the purpose)
  await testdriver.ai('click at coordinates 500, 300');
  ```
</Check>

<Check>
  **Use for exploration, not precision**: For critical assertions, use explicit methods
  
  ```javascript
  // Use AI for setup
  await testdriver.ai('Navigate to the login page');
  
  // Use explicit methods for critical steps
  const usernameField = await testdriver.find('username input');
  await usernameField.click();
  await testdriver.type('testuser');
  
  await testdriver.assert('login page is displayed');
  ```
</Check>

<Warning>
  **AI tasks may be slower**: The AI needs to analyze the screen and plan actions. For performance-critical tests, use explicit methods.
</Warning>

## When to Use AI vs Explicit Methods

### Use `ai()` when:
- Exploring unfamiliar applications
- Handling optional UI elements (popups, cookies, etc.)
- Prototyping tests quickly
- Tasks where exact steps may vary

### Use explicit methods when:
- Performance is critical
- You need precise control
- Making assertions
- Debugging test failures
- Repetitive, predictable actions

## Complete Example

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

describe('E-commerce Flow with AI', () => {
  let testdriver;

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

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

  it('should complete shopping flow using AI assistance', async () => {
    await testdriver.focusApplication('Google Chrome');
    
    // Use AI for navigation and exploration
    await testdriver.ai('Browse to the electronics section');
    await testdriver.ai('Find and add a laptop to the cart');
    
    // Use explicit methods for critical steps
    const cartIcon = await testdriver.find('shopping cart icon');
    await cartIcon.click();
    
    const total = await testdriver.extract('the cart total amount');
    console.log('Cart total:', total);
    
    // Use AI for checkout flow
    await testdriver.ai('Proceed to checkout and fill in shipping details', {
      validateAndLoop: true
    });
    
    // Explicit assertion
    await testdriver.assert('order confirmation page is displayed');
  });
});
```

## Related Methods

- [`find()`](/v7/find) - Locate specific elements
- [`assert()`](/v7/assert) - Make assertions
- [`extract()`](/v7/extract) - Extract information