Skip to main content

​
Overview

The act() 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.act(task, options)

​
Parameters

​
task
string
required
Natural language description of what to do
​
options
object
Execution options

​
Returns

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

​
Examples

​
Basic Usage

// Simple task execution
await testdriver.act('Click the submit button');

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

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

​
With Validation

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

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

​
Multi-Step Workflows

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

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

​
Use Cases

Use AI to explore unfamiliar applications:
await testdriver.act('Explore the main navigation menu');
await testdriver.act('Try to find the user profile settings');
Let AI handle multi-step processes:
await testdriver.act('Complete the multi-step registration form');
await testdriver.act('Configure all the advanced settings to default values');
When exact element locations aren’t critical:
await testdriver.act('Close any popup dialogs');
await testdriver.act('Accept the cookie consent if it appears');

​
Best Practices

Be specific but flexible: Give enough context without over-constraining the AI
// ✅ Good
await testdriver.act('Add the first product to the shopping cart');

// ❌ Too vague
await testdriver.act('do something');

// ❌ Too specific (defeats the purpose)
await testdriver.act('click at coordinates 500, 300');
Use for exploration, not precision: For critical assertions, use explicit methods
// Use AI for setup
await testdriver.act('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');
AI tasks may be slower: The AI needs to analyze the screen and plan actions. For performance-critical tests, use explicit methods.

​
When to Use AI vs Explicit Methods

​
Use act() 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({ newSandbox: true });
  });

  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.act('Browse to the electronics section');
    await testdriver.act('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.remember('the cart total amount');
    console.log('Cart total:', total);
    
    // Use AI for checkout flow
    await testdriver.act('Proceed to checkout and fill in shipping details', {
      validateAndLoop: true
    });
    
    // Explicit assertion
    await testdriver.assert('order confirmation page is displayed');
  });
});