TestDriver: Testes End-to-End

Visão Geral

TestDriver é um revisor de código com IA que realmente executa seu aplicativo. Ele executa automaticamente cada pull request em um sandbox de desktop real, encontra bugs e cria testes de regressão. Os testes controlam navegadores e aplicativos nativos usando descrições de elementos em linguagem natural e visão computacional de IA, e são executados como suítes Vitest. Esta habilidade ensina um agente a criar, executar e depurar testes TestDriver.

Quando Usar Esta Habilidade

• Use quando precisar escrever um teste end-to-end para um aplicativo web ou desktop.
• Use ao automatizar um fluxo de trabalho de UI que não possui seletores estáveis (canvas, Electron, aplicativos nativos).
• Use quando o usuário pedir para verificar se uma página ou fluxo funciona ("verificar se a página de login funciona").
• Use ao depurar um teste TestDriver com falha.

Como Funciona

Etapa 1: Configurar o projeto

npx testdriverai init

Isso gera package.json, testes de exemplo, vitest.config.mjs e um fluxo de trabalho do GitHub Actions. O usuário deve definir TD_API_KEY em .env (obtenha uma chave em https://console.testdriver.ai/team).

Etapa 2: Escrever um teste

Os testes são suítes Vitest usando os hooks do TestDriver:

import { describe, expect, it } from "vitest";
import { TestDriver } from "testdriverai/vitest/hooks";

describe("Login", () => {
  it("signs in successfully", async (context) => {
    const testdriver = TestDriver(context);
    await testdriver.provision.chrome({ url: "https://example.com/login" });

    const email = await testdriver.find("email input field");
    await email.click();
    await testdriver.type("user@example.com");

    const submit = await testdriver.find("Sign In button");
    await submit.click();

    const result = await testdriver.assert("the dashboard is visible");
    expect(result).toBeTruthy();
  });
});

Etapa 3: Executar e iterar

vitest run tests/login.test.mjs

Capturas de tela são tiradas automaticamente antes e depois de cada comando e salvas em .testdriver/screenshots/, nomeadas com o número da linha de origem para facilitar a depuração.

Exemplos

Exemplo 1: Testando um aplicativo desktop (Electron)

await testdriver.provision.electron({ appPath: "./dist/my-app" });
const menu = await testdriver.find("File menu in the menu bar");
await menu.click();

Exemplo 2: Esperando por elementos lentos

const done = await testdriver.find("Loading complete indicator", { timeout: 30000 });
await done.click();

Melhores Práticas

• ✅ Use descrições de elementos específicas ("botão azul de Login no cabeçalho", não apenas "botão").
• ✅ Defina ambos testTimeout e hookTimeout para 900000 em vitest.config.mjs.
• ✅ Adicione chamadas assert() para condições verificáveis de sucesso/falha.
• ✅ Sempre await cada chamada TestDriver.
• ❌ Não use npx vitest; execute vitest run diretamente.
• ❌ Não confie em seletores CSS; o TestDriver localiza elementos visualmente.

Limitações

• Requer uma chave de API TestDriver (TD_API_KEY) e acesso à rede para provisionar sandboxes.
• Funciona apenas com Vitest como executor de testes.
• Esta habilidade não substitui a validação específica do ambiente, testes ou revisão de especialistas.

Notas de Segurança e Proteção

• npx testdriverai init grava arquivos de projeto no diretório atual; execute-o apenas em um projeto que você pretende modificar.
• A credencial TD_API_KEY pertence a .env (ignorado pelo git no scaffold). Nunca a envie.
• Os testes são executados dentro de um sandbox remoto isolado, não na máquina local.

Armadilhas Comuns

• Problema: Hooks de limpeza falham com um timeout de 10s. Solução: Defina hookTimeout: 900000 em vitest.config.mjs; o desmonte do sandbox e o upload de gravações levam mais tempo do que o padrão do Vitest.
• Problema: A rolagem não faz nada. Solução: Um campo de entrada está em foco. Pressione Escape ou clique no fundo da página primeiro, depois role.

Habilidades Relacionadas

• @webapp-testing - Alternativa baseada em Playwright para aplicativos web locais com seletores DOM estáveis.