Pular para conteúdo

Playwright

As ações do Playwright permitem automação moderna do navegador (Chromium, Firefox, WebKit).

Observação importante: apenas métodos anotados com @decorators.robotaction são ações de utilizador e estão documentados aqui.

Ações

playwright.check

Marca checkbox/radio.

Parâmetros:
  • browser
  • locator (obrigatório)
  • timeout (opcional, padrão 30000)
  • force (opcional, padrão False)
Retornar:
  • nenhuma chave de retorno.
Exceções:
  • ElementNotFound quando locator está em falta.

playwright.click

Clica no locator.

Parâmetros:
  • browser
  • locator (obrigatório)
  • timeout (opcional, padrão 30000)
  • button (opcional, padrão left)
  • click_count (opcional, padrão 1)
  • delay (opcional, padrão 0)
  • force (opcional, padrão False)
Retornar:
  • nenhuma chave de retorno.
Exceções:
  • ElementNotFound quando locator está em falta.

playwright.close

Fecha os recursos Playwright atuais e repõe o estado do gestor.

Parâmetros:
  • browser — objeto de metadados do browser.
Retornar:
  • browser — None.

playwright.evaluate_js

Executa expressão JavaScript na página ou no locator.

Parâmetros:
  • browser
  • expression
  • locator (opcional)
  • timeout (opcional, padrão 30000)
Retornar:
  • result

playwright.fill

Preenche o locator com o valor.

Parâmetros:
  • browser
  • locator (obrigatório)
  • value (opcional, cadeia vazia por padrão)
  • timeout (opcional, padrão 30000)
  • force (opcional, padrão False)
  • no_wait_after (opcional, padrão False)
Retornar:
  • nenhuma chave de retorno.
Exceções:
  • ElementNotFound quando locator está em falta.

playwright.get_attribute

Obtém o valor do atributo a partir do locator.

Parâmetros:
  • browser
  • locator (obrigatório)
  • name (obrigatório)
  • timeout (opcional, padrão 30000)
Retornar:
  • value
Exceções:
  • ElementNotFound quando locator está em falta.
  • ValueError quando name está vazio.

playwright.get_by_alt_text

Localiza o elemento pelo texto alternativo.

Parâmetros:
  • browser
  • text
  • exact (opcional, padrão False)
Retornar:
  • locator

playwright.get_by_label

Localiza o controlo de formulário pelo texto da etiqueta.

Parâmetros:
  • browser
  • text
  • exact (opcional, padrão False)
Retornar:
  • locator

playwright.get_by_placeholder

Localiza o input pelo texto do placeholder.

Parâmetros:
  • browser
  • text
  • exact (opcional, padrão False)
Retornar:
  • locator

playwright.get_by_role

Localiza o elemento pelo papel ARIA.

Parâmetros:
  • browser
  • role
  • name (opcional)
  • exact (opcional, padrão False)
Retornar:
  • locator

playwright.get_by_test_id

Localiza o elemento por data-testid.

Parâmetros:
  • browser
  • test_id
Retornar:
  • locator

playwright.get_by_text

Localiza o elemento pelo texto.

Parâmetros:
  • browser
  • text
  • exact (opcional, padrão False)
Retornar:
  • locator

playwright.get_by_title

Localiza o elemento pelo atributo title.

Parâmetros:
  • browser
  • text
  • exact (opcional, padrão False)
Retornar:
  • locator

playwright.get_element

Ação de compatibilidade que devolve um locator para o seletor.

Parâmetros:
  • browser
  • selector
  • index (opcional)
Retornar:
  • element — locator object.

playwright.get_elements

Devolve todos os locators que correspondem ao seletor.

Parâmetros:
  • browser
  • selector
Retornar:
  • elements — lista de locators.
  • length — número de correspondências.
Exceções:
  • ElementNotFound quando não são encontrados elementos.

playwright.get_inner_text

Obtém inner_text do locator.

Parâmetros:
  • browser
  • locator (obrigatório)
  • timeout (opcional, padrão 30000)
Retornar:
  • text
Exceções:
  • ElementNotFound quando locator está em falta.

playwright.get_tabs

Devolve todos os separadores do contexto atual.

Parâmetros:
  • browser
Retornar:
  • tabs — lista com title e url.
  • count

playwright.get_text

Obtém text_content do locator.

Parâmetros:
  • browser
  • locator (obrigatório)
  • timeout (opcional, padrão 30000)
Retornar:
  • text
Exceções:
  • ElementNotFound quando locator está em falta.

playwright.get_title

Obtém o título atual da página.

Parâmetros:
  • browser
Retornar:
  • title

playwright.get_url

Obtém o URL atual da página.

Parâmetros:
  • browser
Retornar:
  • url

playwright.handle_dialog

Regista handler de diálogo (accept ou dismiss).

Parâmetros:
  • browser
  • action (opcional, padrão accept)
  • prompt_text (opcional)
Retornar:
  • nenhuma chave de retorno.
Exceções:
  • ValueError quando action é inválido.

playwright.hover

Passa o rato sobre o locator.

Parâmetros:
  • browser
  • locator (obrigatório)
  • timeout (opcional, padrão 30000)
  • force (opcional, padrão False)
  • modifiers (opcional)
  • position (opcional)
Retornar:
  • nenhuma chave de retorno.
Exceções:
  • ElementNotFound quando locator está em falta.

playwright.is_visible

Verifica a visibilidade do locator.

Parâmetros:
  • browser
  • locator (obrigatório)
  • timeout (opcional, padrão 5000)
Retornar:
  • is_visible
Exceções:
  • ElementNotFound quando locator está em falta.

playwright.locator

Localiza o elemento por seletor CSS/XPath.

Parâmetros:
  • browser
  • selector
  • index (opcional) — quando indicado utiliza locator.nth(index).
Retornar:
  • locator
Exceções:
  • ValueError quando index < 0.

playwright.mock_api

Wrapper conveniente sobre playwright.route para resposta fulfill simulada.

Parâmetros:
  • browser
  • url_pattern
  • response_body (opcional)
  • response_json (opcional)
  • status (opcional, padrão 200)
  • headers (opcional)
Retornar:
  • mesmo retorno que playwright.route (nenhuma chave de retorno).

playwright.navigate

Navega a página para um novo URL.

Parâmetros:
  • browser
  • url
  • timeout (opcional, padrão 30000)
  • wait_until (opcional, padrão load) — load, domcontentloaded, networkidle, commit.
Retornar:
  • nenhuma chave de retorno.

playwright.new_tab

Abre novo separador e opcionalmente navega para o URL.

Parâmetros:
  • browser
  • url (opcional)
Retornar:
  • page — identificador da nova página.

playwright.open

Abre browser/contexto/página e navega para o URL.

Parâmetros:
  • url — URL inicial.
  • headless (opcional, padrão False) — executa o browser sem interface.
  • browser_type (opcional, padrão chromium) — chromium, firefox, webkit.
  • channel (opcional) — canal Chromium (chrome, msedge, etc.).
  • timeout (opcional, padrão 30000) — timeout de navegação em ms.
  • viewport_width / viewport_height (opcional, padrão 1280 / 720) — tamanho da viewport. Ignorado quando maximize=True.
  • maximize (opcional, padrão False) — abre a janela maximizada nativamente; mutuamente exclusivo com viewport_width/viewport_height.
  • locale, timezone_id, user_agent (opcional) — opções de contexto.
  • incognito (opcional, padrão True) — assinatura de compatibilidade.
  • downloads_path (opcional) — diretório onde as transferências são persistidas. Se omitido, o padrão é <assets_path>/downloads (ou <MARVIN_HOME>/temp/downloads como recurso).
Retornar:
  • browser — dicionário de metadados com engine, browser_type, channel, headless, incognito, downloads_path.
Exceções:
  • ImportError quando o Playwright não está instalado.
  • ValueError quando browser_type é inválido.
  • Quando o browser é aberto via chrome.open, é anexado um listener de transferências ao nível do contexto que grava cada transferência em downloads_path automaticamente. O listener resolve nomes sugeridos UUID/sem extensão com pistas de URL e deteção por assinatura de bytes, e evita sobrescritas silenciosas acrescentando um sufixo numérico (ex.: fatura.zip → fatura_2.zip quando fatura.zip já existe). Utilizadores que só usam playwright.open não recebem este listener; use playwright.wait_for_download / playwright.save_download.

playwright.press_key

Pressiona tecla no locator.

Parâmetros:
  • browser
  • locator (obrigatório)
  • key (opcional, padrão Enter)
  • timeout (opcional, padrão 30000)
  • delay (opcional, padrão 0)
Retornar:
  • nenhuma chave de retorno.
Exceções:
  • ElementNotFound quando locator está em falta.

playwright.route

Regista handler de rota de rede.

Parâmetros:
  • browser
  • url_pattern
  • handler_type (opcional, padrão fulfill) — fulfill, continue, abort
  • body (opcional)
  • status (opcional, padrão 200)
  • headers (opcional)
  • json_data (opcional)
Retornar:
  • nenhuma chave de retorno.
Exceções:
  • ValueError quando handler_type é inválido.

playwright.save_download

Grava a transferência num caminho explícito.

Parâmetros:
  • browser
  • download_info (opcional)
  • save_path (obrigatório)
Retornar:
  • saved_path
Exceções:
  • ValueError quando save_path está em falta.

playwright.screenshot

Captura screenshot da página ou do locator.

Parâmetros:
  • browser
  • path (opcional)
  • full_page (opcional, padrão False)
  • timeout (opcional, padrão 30000)
  • locator (opcional)
  • type (opcional, padrão png)
  • quality (opcional)
Retornar:
  • screenshot — bytes quando path não é fornecido.
  • ou nenhuma chave de retorno quando gravado diretamente em ficheiro.

playwright.scroll_into_view

Faz scroll do locator para a vista quando necessário.

Parâmetros:
  • browser
  • locator (obrigatório)
  • timeout (opcional, padrão 30000)
Retornar:
  • nenhuma chave de retorno.
Exceções:
  • ElementNotFound quando locator está em falta.

playwright.select_option

Seleciona <option> por valor, etiqueta ou índice.

Parâmetros:
  • browser
  • locator (obrigatório)
  • value (opcional)
  • label (opcional)
  • index (opcional)
  • timeout (opcional, padrão 30000)
Retornar:
  • nenhuma chave de retorno.
Exceções:
  • ElementNotFound quando locator está em falta.
  • ValueError quando não é fornecido nenhum critério.

playwright.select_tab

Seleciona separador por índice, fragmento de URL ou fragmento de título.

Parâmetros:
  • browser
  • tab_index (opcional)
  • tab_url (opcional)
  • tab_title (opcional)
Retornar:
  • page — identificador da página selecionada.
Exceções:
  • ElementNotFound quando nenhum separador corresponde aos critérios.

playwright.type_text

Escreve o texto carácter a carácter.

Parâmetros:
  • browser
  • locator (obrigatório)
  • text (opcional, cadeia vazia por padrão)
  • delay (opcional, padrão 0)
  • timeout (opcional, padrão 30000)
Retornar:
  • nenhuma chave de retorno.
Exceções:
  • ElementNotFound quando locator está em falta.

playwright.uncheck

Desmarca checkbox.

Parâmetros:
  • browser
  • locator (obrigatório)
  • timeout (opcional, padrão 30000)
  • force (opcional, padrão False)
Retornar:
  • nenhuma chave de retorno.
Exceções:
  • ElementNotFound quando locator está em falta.

playwright.wait_for_download

Aguarda transferência e grava o ficheiro.

Parâmetros:
  • browser
  • timeout (opcional, padrão 30000)
  • save_path (opcional)
Retornar:
  • download
  • download_path
  • suggested_filename
  • url

playwright.wait_for_element

Aguarda o estado do locator.

Parâmetros:
  • browser
  • locator (obrigatório)
  • timeout (opcional, padrão 30000)
  • state (opcional, padrão visible) — visible, hidden, attached, detached.
Retornar:
  • nenhuma chave de retorno.
Exceções:
  • ElementNotFound quando locator está em falta.
  • ValueError quando state é inválido.

playwright.wait_for_element_hide

Aguarda até o locator ficar oculto.

Parâmetros:
  • browser
  • locator (obrigatório)
  • timeout (opcional, padrão 30000)
Retornar:
  • nenhuma chave de retorno.
Exceções:
  • ElementNotFound quando locator está em falta.

playwright.wait_for_navigation

Aguarda navegação/estado de carregamento e correspondência opcional de URL.

Parâmetros:
  • browser
  • timeout (opcional, padrão 30000)
  • url (opcional)
  • wait_until (opcional, padrão load)
Retornar:
  • nenhuma chave de retorno.

playwright.wait_for_url

Aguarda até o URL da página corresponder ao padrão.

Parâmetros:
  • browser
  • url_pattern
  • timeout (opcional, padrão 30000)
Retornar:
  • nenhuma chave de retorno.

playwright.wait_load

Aguarda o estado de carregamento da página.

Parâmetros:
  • browser
  • timeout (opcional, padrão 60000)
  • state (opcional, padrão load) — load, domcontentloaded, networkidle.
Retornar:
  • nenhuma chave de retorno.