Ações do Chrome

Ações do Chrome são ações para interagir com o navegador da Web Chrome.

Todas as ações do Chrome devem usar a instância do navegador, criada pela ação chrome.open.

Identificando um elemento

As ações do Chrome que interagem com um elemento sempre lhe darão a opção de identificar o elemento selector ou element. Quando usar cada um deles?

element: use quando você já tiver o objeto element retornado de qualquer outra ação.

selector: use quando você não tiver o objeto elemento desejado.

Todas as ações permitirão passar apenas selector ou element, mas quando deles deve ser sempre informado.

Usando o selector

Marvin usa o mesmo padrão de seletor que JavaScript, com a seguinte notação:

Classe CSS: para selecionar um elemento pela classe css, deve-se usar . seguido do nome da classe. Exemplo: .menu_class.

ID do elemento: para selecionar um elemento pelo ID, use # seguido pelo ID do elemento. Exemplo: #login.

Nome da tag: para selecionar um elemento pelo nome da tag, basta inserir o nome da tag. Exemplo: tbody

Tag com parâmetro: para selecionar um elemento por tag e parâmetro, use a sintaxe tag[param=value]. Se você quiser usar vários parâmetros, use a sintaxe: tag[param1=value1][param2=value2]

Parâmetro curinga: é possível usar curinga nos parâmetros, usando:

id^=someId: corresponderá a todos os ids começando com someId como someId1, someId-other

id$=someId: corresponderá a todos os ids que terminam com someId como 1someId, other-someId

id*=someId: corresponderá a todos os ids contendo someId como someId1, someId-other, 1someId, other-someId

Ações

chrome.change_select

Altere o valor <select> para o valor fornecido.

Não use selector e element ao mesmo tempo.

Se esta ação for chamada usando selector o evento onChange será acionado automaticamente.

Se esta ação for chamada usando um objeto element, o evento onChange não será acionado. Você pode disparar o evento onChange manualmente usando a ação chrome.execute_js.

Parâmetros:

browser - instância do navegador fornecida por chrome.open.

value - Valor que deve ser definido para o elemento <select>.

selector (opcional) - identificador do elemento no modo seletor (padrão=Nenhum).

element (opcional) - elemento objeto a ser alterado (padrão=Nenhum).

inside (opcional) - este valor define o objeto do elemento onde o selector deve ser encontrado (default=all document).

iframe_search (opcional) - define se o seletor deve ser encontrado no documento base ou em qualquer documento, mesmo dentro de iframes. Se definido True pesquisará dentro de todos os iframes, e se definido False pesquisará apenas dentro do documento principal (padrão=True).

Retornar:

Esta ação não dá retorno

Exceções:

ElementNotFound: se o selector fornecido não corresponder a nenhum elemento na página.

chrome.click_element

Clique com o mouse no meio do elemento dado.

Parâmetros:

browser - instância do navegador fornecida por chrome.open.

selector (opcional) - identificador do elemento no modo seletor (padrão=Nenhum).

element (opcional) - elemento objeto a ser alterado (padrão=Nenhum).

inside (opcional) - este valor define o objeto do elemento onde o selector deve ser encontrado (default=all document).

iframe_search (opcional) - define se o seletor deve ser encontrado no documento base ou em qualquer documento, mesmo dentro de iframes. Se definido True pesquisará dentro de todos os iframes, e se definido False pesquisará apenas dentro do documento principal (padrão=True).

clicks (opcional) - número de cliques a serem realizados na posição (padrão=1)

button (opcional) - define qual botão do mouse deve ser usado para múltiplos cliques 'esquerda', 'meio' ou 'direita' (padrão='esquerda').

interval (opcional) - intervalo entre cada clique, para computadores mais lentos, considere definir um valor maior que default (padrão=0 - instantâneo).

timeout (opcional) - timeout para esperar o elemento aparecer (padrão=5 segundos).

Retornar:

x - X posição do meio do componente

y - Y posição do meio do componente

Exceções:

ElementNotFound: se o selector fornecido não corresponder a nenhum elemento na página.

chrome.close

Fecha a instância do navegador da Web Chrome fornecida

Parâmetros:

browser - instância do navegador fornecida por chrome.open.

Retornar:

Esta ação não dá retorno

chrome.get_tabs

Retorna todas as guias abertas na instância especificada

Parâmetros:

browser - instância do navegador fornecida por chrome.open.

Retornar:

tabs - lista com todos os nomes de guias abertos

chrome.execute_js

Execute uma expressão Javascript na guia atual. Javascript deve ser possível de ser executado em um escopo de página mais alto.

Parâmetros:

browser - instância do navegador fornecida por chrome.open.

expression - Expressão Javascript a ser executada.

await_promise (opcional) - define se a expressão aguardará por qualquer promessa, no caso de expressão assíncrona (default=True).

Retornar:

js_result - objeto com todas as informações sobre a execução do Javascript. Mais informações sobre este objeto podem ser encontradas aqui.

chrome.focus

Defina o foco sobre o elemento fornecido.

Parâmetros:

browser - instância do navegador fornecida por chrome.open.

selector (opcional) - identificador do elemento no modo seletor (padrão=Nenhum).

element (opcional) - elemento objeto a ser alterado (padrão=Nenhum).

inside (opcional) - este valor define o objeto do elemento onde o selector deve ser encontrado (default=all document).

iframe_search (opcional) - define se o seletor deve ser encontrado no documento base ou em qualquer documento, mesmo dentro de iframes. Se definido True pesquisará dentro de todos os iframes, e se definido False pesquisará apenas dentro do documento principal (padrão=True).

Retornar:

Esta ação não dá retorno

Exceções:

ElementNotFound: se o selector fornecido não corresponder a nenhum elemento na página.

chrome.get_element

Retorna o primeiro elemento encontrado para o nome do seletor fornecido.

Parâmetros:

browser - instância do navegador fornecida por chrome.open.

selector (opcional) - identificador do elemento no modo seletor (padrão=Nenhum).

inside (opcional) - este valor define o objeto do elemento onde o selector deve ser encontrado (default=all document).

depth (opcional) - define a profundidade (níveis) dos elementos filhos a serem retornados (padrão=1).

iframe_search (opcional) - define se o seletor deve ser encontrado no documento base ou em qualquer documento, mesmo dentro de iframes. Se definido True pesquisará dentro de todos os iframes, e se definido False pesquisará apenas dentro do documento principal (padrão=True).

Retornar:

element - objeto de elemento para o selector ou None fornecido se nenhum elemento for encontrado.

chrome.get_element_center

Retorne a posição X e Y do centro do elemento fornecido. Se o seletor foi dado retornará o primeiro elemento encontrado para o seletor dado.

Parâmetros:

browser - instância do navegador fornecida por chrome.open.

selector (opcional) - identificador do elemento no modo seletor (padrão=Nenhum).

element (opcional) - elemento objeto a ser alterado (padrão=Nenhum).

inside (opcional) - este valor define o objeto do elemento onde o selector deve ser encontrado (default=all document).

iframe_search (opcional) - define se o seletor deve ser encontrado no documento base ou em qualquer documento, mesmo dentro de iframes. Se definido True pesquisará dentro de todos os iframes, e se definido False pesquisará apenas dentro do documento principal (padrão=True).

Retornar:

x - X posição do meio do componente

y - Y posição do meio do componente

chrome.get_element_position

Retorna o X, Y, largura e altura do elemento dado na tela. Se o seletor foi dado retornará o primeiro elemento encontrado para o seletor dado.

Parâmetros:

browser - instância do navegador fornecida por chrome.open.

selector (opcional) - identificador do elemento no modo seletor (padrão=Nenhum).

element (opcional) - elemento objeto a ser alterado (padrão=Nenhum).

inside (opcional) - este valor define o objeto do elemento onde o selector deve ser encontrado (default=all document).

iframe_search (opcional) - define se o seletor deve ser encontrado no documento base ou em qualquer documento, mesmo dentro de iframes. Se definido True pesquisará dentro de todos os iframes, e se definido False pesquisará apenas dentro do documento principal (padrão=True).

Retornar:

x - Posição esquerda do componente

y - Posição superior do componente

width: largura do componente

height: altura do componente

Exceções:

ElementNotFound: se o selector fornecido não corresponder a nenhum elemento na página.

InvalidPosition: se o selector ou element fornecido não estiver visível.

chrome.get_elements

Retorna o primeiro elemento encontrado para o nome do seletor fornecido.

Parâmetros:

browser - instância do navegador fornecida por chrome.open.

selector (opcional) - identificador do elemento no modo seletor (padrão=Nenhum).

inside (opcional) - este valor define o objeto do elemento onde o selector deve ser encontrado (default=all document).

depth (opcional) - define a profundidade (níveis) dos elementos filhos a serem retornados (padrão=1).

iframe_search (opcional) - define se o seletor deve ser encontrado no documento base ou em qualquer documento, mesmo dentro de iframes. Se definido True pesquisará dentro de todos os iframes, e se definido False pesquisará apenas dentro do documento principal (padrão=True).

Retornar:

elements - lista de objetos de elemento para o seletor fornecido ou lista vazia se nenhum elemento foi encontrado.

length - número de elementos encontrados

chrome.has_download_in_progress

Verifica se há algum download em andamento na instância do browser e retorna True se houver pelo menos um download em andamento ou False se não houver download em andamento.

Parâmetros:

browser - instância do navegador fornecida por chrome.open.

Retornar:

downloads_in_progress - True se houver pelo menos um download em andamento ou False se não houver download em andamento.

chrome.is_element_visible

Verifique se o elemento fornecido está visível ou oculto na tela.

Elementos que são visíveis, mas precisam rolar a tela para serem vistos, são considerados visíveis para esta ação.

Parâmetros:

browser - instância do navegador fornecida por chrome.open.

selector (opcional) - identificador do elemento no modo seletor (padrão=Nenhum).

element (opcional) - elemento objeto a ser alterado (padrão=Nenhum).

inside (opcional) - este valor define o objeto do elemento onde o selector deve ser encontrado (default=all document).

iframe_search (opcional) - define se o seletor deve ser encontrado no documento base ou em qualquer documento, mesmo dentro de iframes. Se definido True pesquisará dentro de todos os iframes, e se definido False pesquisará apenas dentro do documento principal (padrão=True).

timeout (opcional) - timeout para esperar o elemento aparecer (padrão=5 segundos).

Retornar:

is_visible - True se o elemento estiver visível e False se o elemento ainda estiver oculto após o tempo limite.

Exceções:

ElementNotFound: se o selector fornecido não corresponder a nenhum elemento na página.

TimeoutException: se o elemento não estiver visível até que o tempo limite seja atingido

chrome.navigate

Altere a URL do navegador fornecido, navegando até ele.

Parâmetros:

browser - instância do navegador fornecida por chrome.open.

url - novo URL para definir no navegador.

Retornar:

Esta ação não dá retorno

chrome.open

Cria uma nova instância do navegador da Web Chrome para interagir usando o Marvin.

Parâmetros:

url - URL que o Chrome deve abrir

chrome_path - Caminho para o arquivo chrome.exe, se sua instalação não estiver em um dos caminhos de instalação padrão do Chrome: C:\Program Files\Google\Chrome\Application\chrome.exe, C:\ Arquivos de programas (x86)\Google\Chrome\Application\chrome.exe ou C:\Users\<user name>\AppData\Local\Google\Chrome\Application\chrome.exe

Retornar:

navegador - instância do navegador Chrome a ser usada para interações futuras

chrome.query_selector

Retorna o primeiro elemento encontrado para o nome do seletor fornecido.

Parâmetros:

browser - instância do navegador fornecida por chrome.open.

selector (opcional) - identificador do elemento no modo seletor (padrão=Nenhum).

inside (opcional) - este valor define o objeto do elemento onde o selector deve ser encontrado (default=all document).

depth (opcional) - define a profundidade (níveis) dos elementos filhos a serem retornados (padrão=1).

iframe_search (opcional) - define se o seletor deve ser encontrado no documento base ou em qualquer documento, mesmo dentro de iframes. Se definido True pesquisará dentro de todos os iframes, e se definido False pesquisará apenas dentro do documento principal (padrão=True).

Retornar:

element - objeto de elemento para o selector ou None fornecido se nenhum elemento for encontrado.

Exceções:

ElementNotFound: se o selector fornecido não corresponder a nenhum elemento na página

chrome.query_selector_all

Retorna o primeiro elemento encontrado para o nome do seletor fornecido.

Parâmetros:

browser - instância do navegador fornecida por chrome.open.

selector (opcional) - identificador do elemento no modo seletor (padrão=Nenhum).

inside (opcional) - este valor define o objeto do elemento onde o selector deve ser encontrado (default=all document).

depth (opcional) - define a profundidade (níveis) dos elementos filhos a serem retornados (padrão=1).

iframe_search (opcional) - define se o seletor deve ser encontrado no documento base ou em qualquer documento, mesmo dentro de iframes. Se definido True pesquisará dentro de todos os iframes, e se definido False pesquisará apenas dentro do documento principal (padrão=True).

Retornar:

elements - lista de objetos de elemento para o seletor fornecido ou lista vazia se nenhum elemento foi encontrado.

length - número de elementos encontrados

Exceções:

ElementNotFound: se o selector fornecido não corresponder a nenhum elemento na página

chrome.scroll_if_needed

Verifique o elemento fornecido e role a tela se for necessário mostrar o elemento.

Parâmetros:

browser - instância do navegador fornecida por chrome.open.

selector (opcional) - identificador do elemento no modo seletor (padrão=Nenhum).

element (opcional) - elemento objeto a ser alterado (padrão=Nenhum).

inside (opcional) - este valor define o objeto do elemento onde o selector deve ser encontrado (default=all document).

iframe_search (opcional) - define se o seletor deve ser encontrado no documento base ou em qualquer documento, mesmo dentro de iframes. Se definido True pesquisará dentro de todos os iframes, e se definido False pesquisará apenas dentro do documento principal (padrão=True).

Retornar:

Esta ação não dá retorno

Exceções:

ElementNotFound: se o selector fornecido não corresponder a nenhum elemento na página.

chrome.select_tab

Selecione uma guia específica da instância do navegador

Parâmetros:

browser - instância do navegador fornecida por chrome.open.

tab_name - nome/título da guia a ser selecionada. Não precisa ser o nome completo da guia, pois essa ação pesquisa uma guia que contém o nome fornecido em qualquer parte de seu título de maneira que não diferencia maiúsculas de minúsculas.

timeout - quanto tempo (em segundos) esta ação irá esperar até que o tab_name seja encontrado. Isso é útil quando uma nova guia é criada dinamicamente, o que às vezes pode ter um pequeno atraso (padrão = 10 segundos).

Retornar:

Esta ação não dá retorno

Exceções:

ChromeTabNotFound: se o tab_name fornecido não corresponder a nenhum nome/título de guia na instância do navegador.

chrome.wait_downloads

Pare a execução até que todos os downloads em andamento terminem.

Parâmetros:

browser - instância do navegador fornecida por chrome.open.

timeout (opcional) - define o tempo máximo de espera em segundos até que todos os downloads terminem.

Retornar:

Esta ação não dá retorno

Exceções:

TimeoutException: se o elemento não estiver visível até que o tempo limite seja atingido

chrome.wait_element

Pare a execução até que o elemento fornecido esteja presente na página.

Parâmetros:

browser - instância do navegador fornecida por chrome.open.

selector (opcional) - identificador do elemento no modo seletor (padrão=Nenhum).

element (opcional) - elemento objeto a ser alterado (padrão=Nenhum).

inside (opcional) - este valor define o objeto do elemento onde o selector deve ser encontrado (default=all document).

iframe_search (opcional) - define se o seletor deve ser encontrado no documento base ou em qualquer documento, mesmo dentro de iframes. Se definido True pesquisará dentro de todos os iframes, e se definido False pesquisará apenas dentro do documento principal (padrão=True).

timeout (opcional) - define o tempo máximo de espera em segundos para esperar até que o elemento esteja presente na página (padrão=30 segundos).

Retornar:

element - objeto de elemento para o selector ou None fornecido se nenhum elemento for encontrado.

Exceções:

TimeoutException: se o elemento não estiver visível até que o tempo limite seja atingido

chrome.wait_element_hide

Parar a execução util, o elemento fornecido está oculto para o usuário.

Parâmetros:

browser - instância do navegador fornecida por chrome.open.

selector (opcional) - identificador do elemento no modo seletor (padrão=Nenhum).

element (opcional) - elemento objeto a ser alterado (padrão=Nenhum).

inside (opcional) - este valor define o objeto do elemento onde o selector deve ser encontrado (default=all document).

iframe_search (opcional) - define se o seletor deve ser encontrado no documento base ou em qualquer documento, mesmo dentro de iframes. Se definido True pesquisará dentro de todos os iframes, e se definido False pesquisará apenas dentro do documento principal (padrão=True).

timeout (opcional) - define o tempo máximo de espera em segundos para esperar até que o elemento esteja presente na página (padrão=30 segundos).

Retornar:

Esta ação não dá retorno

Exceções:

TimeoutException: se o elemento não estiver visível até que o tempo limite seja atingido

ElementNotFound: se o selector fornecido não corresponder a nenhum elemento na página

chrome.wait_element_visible

Pare a execução até que o elemento fornecido esteja visível para o usuário.

Parâmetros:

browser - instância do navegador fornecida por chrome.open.

selector (opcional) - identificador do elemento no modo seletor (padrão=Nenhum).

element (opcional) - elemento objeto a ser alterado (padrão=Nenhum).

inside (opcional) - este valor define o objeto do elemento onde o selector deve ser encontrado (default=all document).

iframe_search (opcional) - define se o seletor deve ser encontrado no documento base ou em qualquer documento, mesmo dentro de iframes. Se definido True pesquisará dentro de todos os iframes, e se definido False pesquisará apenas dentro do documento principal (padrão=True).

timeout (opcional) - define o tempo máximo de espera em segundos para esperar até que o elemento esteja presente na página (padrão=30 segundos).

Retorna:

element - objeto de elemento para o selector ou None fornecido se nenhum elemento for encontrado.

Exceções:

TimeoutException: se o elemento não estiver visível até que o tempo limite seja atingido

ElementNotFound: se o selector fornecido não corresponder a nenhum elemento na página

chrome.wait_load

Pare a execução até que a página esteja completamente carregada.

Esta ação não cobre o carregamento JavaScript executado na página. Se a página que você está automatizando usar funções de carregamento JavaScript extensas, considere usar chrome.wait_element ou chrome.wait_element_visible

Parâmetros:

browser - instância do navegador fornecida por chrome.open.

timeout (opcional) - define o tempo máximo de espera em segundos para esperar até que a página seja carregada (padrão=60 segundos).

Retornar:

Esta ação não dá retorno

Exceções:

TimeoutException: se o elemento não estiver visível até que o tempo limite seja atingido

Objetos especiais do Chrome

Algumas ações no Chrome usam ou retornam objetos especiais como Element para armazenar informações complexas.

Aqui vamos explicar todos eles e como usá-lo.

Elemento

Retornado por chrome.query_selector contém mais informações sobre o elemento selecionado.

element.get_text()

Retorna o texto dentro do elemento se o elemento tiver um. Este método apenas retorna o texto diretamente dentro do elemento, não retornando textos de elementos filhos.

Retorna:

Texto dentro do elemento, se houver, ou Nenhum, se não houver texto nesse elemento.

element.get_attribute(attribute_name)

Retorna o texto dentro do elemento se o elemento tiver um. Este método apenas retorna o texto diretamente dentro do elemento, não retornando textos de elementos filhos.

Parâmetros:

attribute_name - nome/chave do atributo a ser retornado.

Retorna:

O valor do atributo fornecido.

resultado do execucte_js

Após executar uma expressão Javascript no navegador, ele retornará um objeto com estas chaves:

type - Tipo do objeto retornado (object, function, undefined, string, number, boolean, symbol, bigint, wasm)

subtype - Subtipo do objeto retornado no caso do tipo ser object ou wasm (array, null, node, regexp, date, map, set, Weakmap, Weakset, iterator, generator, error, proxy, promessa, typedarray, arraybuffer, dataview, i32, i64, f32, f64, v128, externref)

className - Definido para o objeto type, dá o nome da classe (construtor) do objeto.

value - Valor retornado para o tipo informado.