Visão geral da automação por scripts

O Guida inclui um ambiente completo de automação por scripts para navegador. Scripts interagem com páginas, gerenciam dados e orquestram fluxos por meio da API g.*.

Mecanismos de script

Três mecanismos estão disponíveis:

• JavaScript (ClearScript V8) — compatibilidade ES2024+, top-level await, Promises nativas e imports ES module. Usa o mesmo V8 do Chrome e Node.js.
• Lua (LuaCSharp) — API limpa baseada em tabelas com sintaxe Lua padrão. Integra-se a bibliotecas do espaço de trabalho via require().
• Janet (JanetSharp) — dialeto Lisp funcional e expressivo com estruturas de dados imutáveis e mecanismo PEG integrado.

Os três mecanismos compartilham a mesma superfície de API g.*.

Por que Janet?

JavaScript é ótimo pela familiaridade, mas o Guida inclui Janet para usuários que preferem um dialeto Lisp funcional e altamente expressivo. As estruturas imutáveis e o mecanismo PEG integrado do Janet são especialmente úteis para extrair e transformar dados web bagunçados.

Estrutura básica e top-level await

Como scripts de automação são essencialmente assíncronos, o Guida oferece suporte a top-level await para scripts que não precisam de um return antecipado:

// Top-level await funciona imediatamente
const tabs = g.tabs.getTabs();
g.log("Guias abertas: " + tabs.length);

Para scripts que precisam retornar cedo, envolva o código em async function main() e chame await main(); no fim.

Pressione F5 no editor de scripts para executar.

Tratamento de erros

O tratamento de erro depende do mecanismo usado.

JavaScript e Janet: exceções

Em JavaScript e Janet, todos os métodos g.* retornam valores diretamente e lançam exceções em erro. Em JavaScript, use try/catch:

try {
  await g.dom.click("#submit");
} catch (e) {
  g.log("Clique falhou: " + e.message);
  return;
}

Lua: retornos múltiplos

Em Lua, a API g.* usa retornos múltiplos idiomáticos (nil, error) em vez de lançar exceções. Isso evita que o depurador do Visual Studio pare em exceções “não tratadas” durante o desenvolvimento.

Sempre verifique o primeiro retorno:

local success, err = g.nav.navigateToUrl("https://example.com")
if not success then
    g.log("Erro: falha na navegação: " .. err)
else
    g.log("Página carregada com sucesso")
end

Métodos assíncronos

Muitas operações de navegador são assíncronas. Em JavaScript, use await. Em Lua e Janet, o mecanismo aguarda automaticamente:

JavaScript:

async function main() {
  await g.nav.navigateToUrl("https://example.com");
  await g.dom.waitForDomStable();
  const html = await g.page.getDom();
  g.log("Página carregada, tamanho do DOM: " + html.length);
}

Lua:

g.nav.navigateToUrl("https://example.com")
g.dom.waitForDomStable()
local html = g.page.getDom()
g.log("Página carregada, tamanho do DOM: " .. #html)

Janet:

(g.nav.navigateToUrl "https://example.com")
(g.dom.waitForDomStable)
(def html (g.page.getDom))
(g.log (string "Página carregada, tamanho do DOM: " (length html)))

Bibliotecas compartilhadas

O Guida permite escrever funções reutilizáveis em arquivos compartilhados.

JavaScript (ES Modules)

Use a sintaxe padrão import/export. O caminho é resolvido em relação ao diretório do script chamador, com fallback para a raiz do espaço de trabalho.

lib/helpers.js:

export async function loginToApp(username, password) {
  await g.nav.navigateToUrl("https://example.com/login");
  await g.dom.enterText("#user", username);
  await g.dom.enterText("#pass", password);
  await g.dom.click("#submit");
}

myscript.js:

import { loginToApp } from "./lib/helpers.js";

await loginToApp("admin", "secure123");
const data = await g.dom.extractContent(".stats");
g.log("Estatísticas do painel: " + data);

Lua (módulos)

Use a função padrão require(). O Guida procura módulos na pasta lib/ do espaço de trabalho e nas pastas lib/ e scripts/ do fluxo atual.

lib/utils.lua:

local M = {}
function M.hello() g.log("Olá da biblioteca!") end
return M

myscript.lua:

local utils = require("utils")
utils.hello()

Janet (módulos)

Use a macro import para carregar módulos Janet das pastas lib/ e scripts/ do espaço de trabalho.

lib/utils.janet:

(defn hello []
  (g.log "Olá da biblioteca Janet!"))

myscript.janet:

(import utils)
(utils/hello)

Pragma de timeout

Defina um timeout de execução do script em milissegundos:

// @timeout 60000

async function main() {
  // Este script será cancelado após 60 segundos
}

O timeout padrão é 10 segundos. Coloque o pragma antes de qualquer código.

Pragma de contexto

Proteja scripts que dependem de g.worker.getContext() contra execução fora de contexto de worker:

// @require-context

async function main() {
  const ctx = g.worker.getContext();
  // Este script só roda dentro de um processador de fila ou grupo de processos de trabalho
}

Se o script for executado sozinho (F5, MCP, gatilho de evento), ele falha imediatamente com erro claro em vez de falhar no meio da execução. Veja Filas e revisão para detalhes.

Logging

Use g.log() para escrever no painel Console:

g.log("Processando item: " + item.name);

Editor de scripts

O editor integrado oferece:

• IntelliSense — completações para todos os métodos g.* e seus parâmetros
• Signature help — dicas de parâmetros ao digitar (
• Hover docs — informações de tipo ao passar o mouse
• Depuração com Chrome DevTools — clique no botão Debug em qualquer arquivo .js para abrir uma instância externa do Chrome DevTools conectada diretamente ao V8
• Localizar/substituir — com suporte a regex
• Correspondência de chaves e guias de indentação

Navegação stealth

Alguns sites detectam navegadores automatizados. Use stealth: true para injetar patches anti-detecção antes dos scripts da página:

await g.nav.navigateToUrl("https://example.com", { stealth: true });

Isso aplica cinco patches: oculta navigator.webdriver, injeta window.chrome.runtime, corrige Permissions.prototype.query, simula navigator.plugins e define navigator.languages como ["en-US", "en"].

Para controle granular, passe um objeto StealthOptions para ativar/desativar patches individuais. Você também pode detectar redirecionamentos baseados em JavaScript com { detectRedirects: true }. Veja a Referência da API para detalhes.

Texto para fala

O Guida inclui texto para fala via Windows Speech Synthesis. Configure voz padrão e taxa de fala em Settings > TTS.

Scripts podem falar texto e sobrescrever padrões por chamada:

await g.tts.speak("Processamento concluído", { voice: "Microsoft David", rate: 2 });

Veja a Referência da API para todos os métodos.

Diferenças do Lua

Todos os métodos de automação do Guida estão disponíveis no namespace global g. JavaScript e Lua compartilham a mesma superfície de API, mas há duas diferenças importantes:

1. Sintaxe com ponto, não dois-pontos

Diferente de algumas integrações C# com Lua, a API do Guida usa o operador ponto (.) para todas as chamadas, por exemplo g.dom.click("#btn"). Não use o operador dois-pontos (:), como g.dom:click, porque os métodos são vinculados diretamente a serviços C# e não esperam um argumento self.

2. Tabelas

Lua usa tabelas para estruturas de dados. Quando um método retorna um objeto, como uma guia ou documento do armazenamento, ele é retornado como tabela Lua com indexação padrão baseada em 1 para arrays.

-- Trabalhando com o armazenamento de documentos
local doc, err = g.store.get("products", "item-1")
if doc and doc.data then
    g.log("Produto encontrado: " .. doc.data.name)
end

Diferenças do Janet

Janet é uma linguagem funcional parecida com Lisp. Sua sintaxe é baseada em s-expressions e notação prefixada.

1. Chamadas de função

Em vez de usar notação de ponto com parênteses externos como g.dom.click("#btn"), você envolve a expressão inteira em parênteses: (g.dom.click "#btn").

2. Dicionários e structs

Quando um método retorna um objeto, como TabInfo ou documento do armazenamento, ele é retornado como dicionário Janet. Acesse propriedades com get ou get-in:

# Trabalhando com o armazenamento de documentos
(def doc (g.store.get "products" "item-1"))
(if doc
  (g.log (string "Produto encontrado: " (get (get doc "data") "name"))))

Próximos passos

• Referência da API — listagem completa de métodos para todos os namespaces g.*
• Receitas — scripts práticos baseados em exemplos reais do aplicativo
• Espaços de trabalho — organize scripts, dados e configuração em pastas de espaço de trabalho
• Início rápido — passo a passo prático de 5 minutos