/testdriver-ai

name: testdriver:ai
description: Execute natural language tasks using 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

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

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

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

// 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:

    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:

    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:

    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

  // ✅ 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

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

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