Dirigindo o aplicativo Electron

Visão Geral

scripts/drive.mjs inicia o aplicativo Electron do projeto sob o Playwright em um daemon em segundo plano e o mantém em execução entre os comandos, de modo que cada ação (clicar, digitar, tirar instantâneo, capturar tela, avaliar) seja uma chamada rápida de shell. Cada inicialização usa um perfil temporário, para que o agente possa verificar uma alteração na interface do usuário ou reproduzir um bug no aplicativo real, não apenas em testes unitários, sem tocar nos dados do usuário.

Quando Usar Esta Habilidade

• Use quando precisar verificar uma alteração na interface do usuário no aplicativo Electron em execução.
• Use ao reproduzir um bug no renderizador ou na inicialização, ou uma falha que só aparece na compilação de produção (por exemplo, uma CSP mais rigorosa).
• Use ao verificar as telas de primeira execução, integração ou configurações.
• Use ao exercitar um recurso de ponta a ponta, incluindo IPC através da ponte de pré-carregamento ou código no processo principal.
• Não o use para aplicativos web sem Electron, ou para fluxos de várias janelas (veja Limitações).

Como Funciona

Etapa 1: Verificar pré-requisitos

scripts/drive.mjs, no diretório desta habilidade, encontra o projeto pelo package.json mais próximo, então execute-o de qualquer lugar dentro do projeto. Defina DR para seu caminho absoluto.

Ele precisa de electron e playwright-core (1.49 ou posterior) instalados no projeto. Se start disser que um deles está faltando, informe o usuário em vez de instalá-lo você mesmo. As configurações de inicialização vêm de drive.config.json na raiz do projeto (veja Etapa 4); sem arquivo, ele executa electron ..

Etapa 2: Iniciar, olhar, agir, parar

DR=<this skill's directory>/scripts/drive.mjs

$DR start                  # last build, profile 'default'; prints status
$DR snapshot               # accessibility tree: find what to click, by role and name
$DR click 'role=button[name="Get started"]'
$DR fill 'role=textbox[name="Email"]' 'test@example.com'
$DR wait 'text=Welcome'
$DR screenshot             # prints a PNG path; Read it to see the window
$DR logs --lines 80        # main and renderer console, plus the config's logFile
$DR stop                   # ALWAYS, before finishing

• Opções de inicialização:
  • --build: execute o comando build da configuração primeiro. Necessário após qualquer alteração de origem se o aplicativo for executado a partir de uma compilação, porque a compilação está caso contrário, desatualizada; start imprime sua idade.
  • --fresh: limpe o perfil temporário, o que lhe dá o estado de primeira execução do aplicativo.
  • --profile <name>: um perfil temporário separado.
  • --dev: veja Etapa 5.
• Alvos são seletores do Playwright. Prefira role=button[name="…"] da saída snapshot, depois text=…, depois CSS.
• -- encerra os sinalizadores. Coloque-o antes de texto que começa com hifens: $DR fill 'role=textbox[name="Args"]' -- --verbose.
• Outros comandos: select <target> <value|label>, press <key>, status, screenshot --selector <css>. $DR help lista tudo.

Etapa 3: Executar código no aplicativo

eval <js> é executado no renderizador, main <js> no processo principal (electron e process estão em escopo, require não está). Use uma expressão simples, ou um corpo com return. - lê o código da entrada padrão, o que evita completamente as aspas. O resultado retorna como JSON, então retorne dados simples: um nó DOM ou uma função retorna como undefined ou {}.

Para exercitar o IPC, chame o que a pré-carga do aplicativo expõe através de eval. Isso passa pela ponte de pré-carga real, como o próprio código do renderizador do aplicativo faz.

Etapa 4: Configurar a inicialização (opcional)

drive.config.json na raiz do projeto; cada campo é opcional:

{
  "build": "npm run build",
  "args": ["."],
  "env": { "APP_DATA_DIR": "{profile}/data" },
  "logFile": "logs/main.log",
  "dev": {
    "args": ["."],
    "env": { "ELECTRON_RENDERER_URL": "http://localhost:5173" },
    "url": "http://localhost:5173"
  }
}

• args: com o que o Electron é iniciado: um diretório de aplicativo cujo package.json main é o ponto de entrada compilado, ou o próprio arquivo de entrada.
• env: adicionado ao ambiente do aplicativo. {profile} se torna o diretório do perfil temporário (apenas em valores env, não em args). É assim que os dados mantidos fora de userData são redirecionados: APP_DATA_DIR é apenas um exemplo de nome, e só tem efeito se o aplicativo o ler. Verifique o código-fonte do aplicativo para a variável que ele realmente usa.
• logFile: um arquivo de log relativo ao diretório do perfil, mostrado por logs.

Se um projeto não tiver configuração e start falhar ou iniciar a coisa errada, descubra esses valores a partir da configuração de compilação e do package.json do projeto, então sugira um drive.config.json ao usuário.

…