Bem vindo a documentação do Mink!¶

Interação Básica no Navegador¶

Agora que sua sessão está iniciada, você irá querer abrir uma página com ele. Apenas depois de começar, a sessão não está em uma página qualquer (em um navegador real, você estaria na página about:blank), e chamando qualquer outra ação é provável que falhe.

$session->visit('http://meu_projeto.dev/alguma_pagina.php');

Interagindo com a Página¶

A sessão dá acesso a página através do método Session::getPage. Isto lhe permite analisar a página e interagir com elas. Os próximos capítulos cobrem a página API com profundidade. A maioria do que você vai fazer com Mink usará este objeto, mas você pode continuar lendo para saber mais sobre Sessão.

Usando o Histórico do Navegador¶

A sessão lhe da acesso ao histórico do navegador:

// obter a URL da página atual:
echo $session->getCurrentUrl();

// usar controles de histórico:
$session->reload();
$session->back();
$session->forward();

Gerenciamento de Cookie¶

A sessão pode manipular cookies disponíveis no navegador.

// definir cookie:
$session->setCookie('cookie nome', 'valor');

// obter cookie:
echo $session->getCookie('cookie nome');

// deletar cookie:
$session->setCookie('cookie nome', null);

Código de Status de Recuperação¶

A sessão lhe permite recuperar o código HTTP do status da resposta:

echo $session->getStatusCode();

Gerenciamento de Headers¶

A sessão lhe permite manipular request de headers e acessar a resposta dos headers:

// definindo linguagem do navegador:
$session->setRequestHeader('Accept-Language', 'fr');

// recuperação da resposta do headers:
print_r($session->getResponseHeaders());

Autenticação HTTP¶

A sessão tem um método especial para atuar na autenticação básica de HTTP:

$session->setBasicAuth($user, $password);

O método pode também ser usado para reiniciar uma autenticação prévia:

$session->setBasicAuth(false);

Avaliação do Javascript¶

A sessão lhe permite executar ou avaliar Javascript.

// Executar JS
$session->executeScript('document.body.firstChild.innerHTML = "";');

// analisar expressão JS:
echo $session->evaluateScript(
    "return 'algo a partir do navegador';"
);

Você pode também esperar até uma determinada expressão JS retornar um valor booleano verdadeiro ou o tempo limite ser atingido:

// esperar por N milissegundos ou
// até a expressão JS tornar-se verdadeira:
$session->wait(
    5000,
    "$('.suggestions-results').children().length"
);

Repondo a Sessão¶

O objetivo primário para o Mink é prover um navegação na WEB API única consistente para teste de aceite. Mas uma parte muito importante no teste é o isolamento.

O Mink provê dois métodos muito úteis para isolar testes, que podem ser usados em seus métodos de teste destruir:

// soft-reset:
$session->reset();

// hard-reset:
$session->stop();
// ou se você quiser iniciar novamente ao mesmo tempo
$session->restart();

Parar a sessão é a melhor maneira de reiniciar a sessão ao estado inicial. Ele irá fechar o seu navegador inteiramente. Para usar a sessão novamente, você precisa iniciar a sessão antes de qualquer outra ação. O atalho Session::restart permite você fazer estas 2 chamadas em uma única.

A desvantagem de fechar o navegador e iniciá-lo novamente é que leva tempo. Em muitos casos, um nível mais baixo de isolamento é o suficiente a favor de uma reinicialização rápida. O método Session::reset cobre este caso de uso. Ele irá tentar limpar os cookies e reiniciar o request de headers e o histórico do navegador ao limite das possibilidades do driver.

Levando tudo isto em conta, por padrão é recomendado usar Session::reset() e chamar Session::stop() quando você realmente precisar de isolamento completo.

DocumentElement e NodeElement¶

O Elemento API consiste em 2 classes principais. A instância DocumentElement representa a página a ser exibida no navegador, enquanto a classe NodeElement é usada para representar qualquer elemento dentro da página. Ambas classes compartilham um conjunto comum de métodos para analisar a página (definidos em TraversableElement).

A instância DocumentElement é acessível através do método Session::getPage:

$page = $session->getPage();

// Agora você pode manipular a página.

Métodos de Análise¶

Elementos tem 2 métodos principais: ElementInterface::findAll retorna um array de instâncias NodeElement correspondentes ao seletor fornecido dentro do elemento atual enquanto ElementInterface::find retorna a primeira combinação ou null quando não há ninguém.

A classe TraversableElement também provê um grupo de métodos atalho no topo do find() para torná-lo mais fácil de conseguir muitos casos de uso em comum:

ElementInterface::has

Checa se um elemento filho combina com um dado seletor, mas sem devolvê-lo.

TraversableElement::findById

Procura um elemento filho com um dado id.

TraversableElement::findLink

Procura um link com um dado texto, title, id ou atributo alt (para imagens usadas dentro de links).

TraversableElement::findButton

Procura por um botão com um dado texto, title, id, atributo name ou um atributo alt (para imagens usadas dentro de links).

TraversableElement::findField

Procura por um campo (input, textarea ou select) com um dado label, placeholder, id ou atributo name.

$formularioRegistrar = $page->find('css', 'form.registrar');

if (null === $formularioRegistrar) {
    throw new \Exception('O elemento não foi encontrado');
}

// busca algum campo DENTRO do formulário com a class="registrar"
$campo = $formularioRegistrar->findField('Email');

Seletores¶

Os métodos ElementInterface::find e ElementInterface::findAll suporta vários tipos de seletores para encontrar elementos.

$titulo = $page->find('css', 'h1');

$iconeBotao = $page->find('css', '.btn > .icon');

$ancorasSemUrl = $page->findAll('xpath', '//a[not(@href)]');

$valorEscapado = $session->getSelectorsHandler()->xpathLiteral('Go to top');

$topLink = $page->find('named', array('link', $valorEscapado));

$selector = new \App\MySelector();

$handler = new \Behat\Mink\Selector\SelectorsHandler();
$handler->registerSelector('mine', $selector);

$driver = // ...

$session = new \Behat\Mink\Session($driver, $handler);

Obtendo o nome da tag¶

O método NodeElement::getTagName lhe permite obter o nome da tag do elemento. Este nome é sempre retornado em letras minúsculas.

$el = $page->find('css', '.something');

// obter o nome da tag:
echo $el->getTagName(); // exibe 'a'

Acessando atributos HTML¶

A classe NodeElement lhe dá acesso aos atributos HTML do elemento.

NodeElement::hasAttribute

Verifica se o elemento tem um determinado atributo.

NodeElement::getAttribute

Obtém o valor de um atributo.

NodeElement::hasClass

Verifica se o elemento tem uma dada classe (convenientemente envolvido em torno de getAttribute('class')).

$el = $page->find('css', '.something');

if ($el->hasAttribute('href')) {
    echo $el->getAttribute('href');
} else {
    echo 'Esta âncora não é um link. Ela não tem um href.';
}

Elemento de Conteúdo e Texto¶

A classe Element provê acesso ao conteúdo dos elementos.

Element::getHtml

Obtém o HTML interno do elemento, por exemplo todos os filhos do elemento.

Element::getOuterHtml

Obtém o HTML exterior do elemento, por exemplo incluindo o próprio elemento.

Element::getText

Obtém o texto do elemento.

Verificando a visibilidade de um Elemento¶

O método NodeElement::isVisible permite checar se o elemento está visível.

Acessando o estado do formulário¶

A classe NodeElement permite o acesso ao estado de elementos do formulário:

NodeElement::getValue

Obtém o valor do elemento. Veja Interagindo com formulários.

NodeElement::isChecked

Verifica se o checkbox ou o radio button está checado.

NodeElement::isSelected

Verifica se o elemento <option> está selecionado.

Interagindo com Links e Botões¶

Os métodos NodeElement::click e NodeElement::press lhe permitem clicar nos links e apertar os botões na página.

Interagindo com formulários¶

A classe NodeElement tem um conjunto de métodos permitindo interagir com formulários:

NodeElement::getValue

pega o valor de um campo do formulário. O valor depende do tipo do campo:

• o valor da opção selecionada para caixas de seleção individuais (ou null quando nenhuma é selecionada) ;
• um array dos valores das opções selecionadas para multiplas caixas de seleção;
• o valor do campo checkbox quando checado, ou null quando não checado;
• o valor do radio button selecionado no grupo de radio para radio buttons;
• o valor do campo para campos de texto e textareas;
• um valor indefinido para campos de arquivos (devido as limitações do navegador).

NodeElement::setValue

coloca o valor em um campo do formulário

• para um campo de arquivo, deve ser o caminho para o arquivo;
• para um checkbox, deve ser um booleano indicando se está checado;
• para outros campos, deve corresponder o comportamento de getValue.

NodeElement::isChecked

informa se um radio button ou um checkbox está checado.

NodeElement::isSelected

informa se um elemento <option> está selecionado.

NodeElement::check

checa um campo checkbox.

NodeElement::uncheck

descheca um campo checkbox.

NodeElement::selectOption

seleciona uma opção em uma caixa de seleção ou em um radio group.

NodeElement::attachFile

anexa um arquivo em uma em uma entrada de arquivo.

NodeElement::submit

submete o formulário.

Interagindo com o mouse¶

A classe NodeElement oferece um conjunto de métodos que permitem interagir com o mouse:

NodeElement::click

executa um clique no elemento.

NodeElement::doubleClick

executa um clique duplo no elemento.

NodeElement::rightClick

executa um clique com o botão direito no elemento.

NodeElement::mouseOver

move o mouse para cima do elemento.

Interagindo com o teclado¶

O mink permite você interagir com o teclado graças aos métodos NodeElement::keyDown, NodeElement::keyPress e NodeElement::keyUp.

Manipulando o Foco¶

A classe NodeElement permite você dar e remover o foco em um elemento graças aos métodos NodeElement::focus e NodeElement::blur.

Clica e arrasta¶

Mink provê o clica e arrasta de um elemento para outro:

$arrastado = $page->find(...);
$alvo = $page->find(...);

$arrastado->dragTo($alvo);

Métodos de atalho¶

A classe TraversableElement provê alguns poucos métodos de atalho permitindo procurar um elemento filho na página e executar uma ação imediatamente:

TraversableElement::clickLink

Olha para um link (veja findLink) e clica nele.

TraversableElement::pressButton

Olha para um botão (veja findButton) e o pressiona.

TraversableElement::fillField

Olha para um campo (veja findField) e coloca um valor nele.

TraversableElement::checkField

Olha para um checkbox (veja findField) e checa ele.

TraversableElement::uncheckField

Olha para um checkbox (veja findField) e descheca ele.

TraversableElement::selectFieldOption

Olha para um select ou radio group (veja findField) e seleciona uma opção.

TraversableElement::attachFileToField

Olha para um campo de arquivo (veja findField) e anexa um arquivo a ele.

Suporte a recursos do driver¶

Apesar do Mink fazer o seu melhor em remover as diferenças entre navegador e diferentes emuladores de navegador, ele não pode fazer muito em alguns casos. Por exemplo, BrowserKitDriver não avalia JavaScript e Slenium2Driver não consegue pegar código dos status das respostas. Nestes casos, o driver sempre irá lançar uma exceção Behat\Mink\Exception\UnsupportedDriverActionException.