How to build a bot for filling web forms

Each form has its own structure — describe declaratively:

// forms/lead-intake.ts
export const leadIntakeForm = {
  url: 'https://competitor.com/contact',
  steps: [
    { field: 'input[name="email"]', value: (data) => data.email, type: 'fill' },
    { field: 'input[name="firstName"]', value: (data) => data.firstName, type: 'fill' },
    { field: 'select[name="industry"]', value: (data) => data.industry, type: 'select' },
    { field: 'textarea[name="message"]', value: (data) => data.message, type: 'fill' },
    { field: 'input[name="consent"]', type: 'check' },
    { field: 'button[type="submit"]', type: 'click' },
  ],
  successIndicator: 'text=Thank you',
  errorIndicators: ['text=Please fill', '.field-error'],
};

Generic runner that executes the form descriptor:

async function runForm(formDesc, data) {
  const browser = await chromium.launch({ headless: true });
  const context = await browser.newContext();
  const page = await context.newPage();
  
  try {
    await page.goto(formDesc.url, { waitUntil: 'networkidle' });
    
    for (const step of formDesc.steps) {
      const locator = page.locator(step.field);
      await locator.waitFor({ state: 'visible', timeout: 10000 });
      
      switch (step.type) {
        case 'fill':
          await locator.fill(step.value(data));
          break;
        case 'select':
          await locator.selectOption(step.value(data));
          break;
        case 'check':
          await locator.check();
          break;
        case 'click':
          await locator.click();
          break;
        case 'upload':
          await locator.setInputFiles(step.value(data));
          break;
      }
      
      await sleep(rand(300, 800)); // human-like timing
    }
    
    // Wait for outcome
    const success = page.locator(formDesc.successIndicator);
    const error = page.locator(formDesc.errorIndicators.join(', '));
    await Promise.race([
      success.waitFor({ timeout: 30000 }),
      error.waitFor({ timeout: 30000 }),
    ]);
    
    const isSuccess = await success.isVisible();
    const screenshot = await page.screenshot({ fullPage: true });
    
    return { success: isSuccess, screenshot };
  } finally {
    await browser.close();
  }
}

1000 forms to submit. After 300 the process dies. Without idempotency: you start from zero, 300 duplicates. With idempotency: you continue from 301.

CREATE TABLE form_submissions (
  id BIGSERIAL PRIMARY KEY,
  external_id TEXT UNIQUE NOT NULL,  -- unique per data row
  form_id TEXT NOT NULL,
  status TEXT NOT NULL CHECK (status IN ('pending', 'submitted', 'failed')),
  data JSONB NOT NULL,
  screenshot_path TEXT,
  attempts INT NOT NULL DEFAULT 0,
  last_error TEXT,
  submitted_at TIMESTAMPTZ
);

CREATE INDEX idx_form_status ON form_submissions (form_id, status);

async function processBatch(formDesc, dataRows) {
  for (const data of dataRows) {
    const externalId = generateId(data); // e.g. email + timestamp
    
    // Skip if already submitted
    const existing = await db.query(
      'SELECT status FROM form_submissions WHERE external_id=$1',
      [externalId]
    );
    if (existing.rows.length && existing.rows[0].status === 'submitted') {
      continue; // idempotent
    }
    
    // Insert pending
    await db.query(`
      INSERT INTO form_submissions (external_id, form_id, status, data)
      VALUES ($1, $2, 'pending', $3)
      ON CONFLICT (external_id) DO UPDATE SET attempts = form_submissions.attempts + 1
    `, [externalId, formDesc.id, data]);
    
    try {
      const result = await runForm(formDesc, data);
      await db.query(`
        UPDATE form_submissions SET status=$1, screenshot_path=$2, submitted_at=NOW()
        WHERE external_id=$3
      `, [result.success ? 'submitted' : 'failed', result.screenshotPath, externalId]);
    } catch (err) {
      await db.query(`
        UPDATE form_submissions SET status='failed', last_error=$1
        WHERE external_id=$2
      `, [err.message, externalId]);
    }
  }
}

Wizard forms (step 1 → step 2 → review → submit). Each step has a "Next" button. File uploads via setInputFiles:

// Multi-step descriptor
const visaApplicationForm = {
  url: 'https://gov.example.com/visa-application',
  steps: [
    // Step 1: Personal info
    { field: 'input[name="firstName"]', type: 'fill', value: d => d.firstName },
    { field: 'input[name="lastName"]', type: 'fill', value: d => d.lastName },
    { field: 'input[name="dateOfBirth"]', type: 'fill', value: d => d.dob },
    { field: 'button:has-text("Next")', type: 'click', waitAfter: 2000 },
    
    // Step 2: Documents (file upload)
    { field: 'input[name="passport-scan"]', type: 'upload', value: d => d.passportPath },
    { field: 'input[name="photo"]', type: 'upload', value: d => d.photoPath },
    { field: 'button:has-text("Next")', type: 'click', waitAfter: 2000 },
    
    // Step 3: Review and submit
    { field: 'input[name="confirm"]', type: 'check' },
    { field: 'button[type="submit"]', type: 'click' },
  ],
  successIndicator: 'text=Application submitted',
  errorIndicators: ['.error', 'text=Invalid'],
};