Escrevendo testes com PHPT e contribuindo com o PHP

Este ano esteve em destaque a PHPTestFest09, sendo realizada em vários cantos do mundo e destacando-se a participação do PHPSP que contribuiu com o maior número de testes. Ficou de fora? Então já comece a se preparar para ano que vem.

O PHPT é um framework extremamente simples de testes criado e usado internamente pelos desenvolvedores do core. Ele é extremamente atômico e centrado em testes como os que esperamos do PHP, como testar funções e bugs específicos.

O que preciso saber?

A grande vantagem do PHPT é que para poder escrever um teste, tudo que você precisa saber é: como escrever código PHP. Claro que um pouco de conhecimento interno do funcionamento do PHP vai te ajudar a procurar detalhes para testar, mas sabendo escrever PHP você já pode contribuir com uma grande percentagem dos testes que precisamos.

Vamos então atacar por partes:

1. Preparando o ambiente
2. Escolhendo um teste
3. Escrevendo um teste
4. Rodando um teste
5. Enviando seu teste para o PHP

1. Preparando o Ambiente

A preparação do ambiente não é nada complicada e exemplos estão disponíveis para referencia. A primeira coisa que você precisa é da versão do PHP que vai precisar para rodar testes. No caso do TestFest focamos no PHP 5.3, no momento recomendo pegar as últimas disponíveis na página do PHP QA (qa.php.net ) vá lá e baixe o pacote (source ou binary para windows).

Em ambientes Linux/Mac Os X, você irá passar pelo processo de compilar o PHP, passando pelos processos normais de "./configure", “make” mas antes de rodar o “make install”, você poderá rodar o comando “make tests”. Este comando irá rodar todos os testes do PHP (em torno de 900+), pode demorar, mas é um ótimo procedimento, pois ao final você poderá mandar um relatório para a equipe de QA e “fazer sua parte”. Rode também o comando make install pois durante a confecção de um teste será interessante você poder testar ele com a versão correta do PHP.

Mais pra frente vamos ver como usar o make tests para rodar os seus novos testes.

2. Escolhendo um teste

Antes de escrever um teste é necessário escolher o objeto de nosso teste. Para tal é preciso identificar um ponto do PHP que necessita de um teste, isto pode vir de duas fontes, um bug ou uma linha de código não “coberta” (code coverage). Para descobrir bugs com/sem testes a melhor forma é olhando a pasta de testes da extensão do bug (GD -> /ext/gd/tests) ou conversando com o pessoal na lista do QA.

Para testes específicos de linhas de código sua melhor aposta é o site http://gcov.php.net onde você deve navegar até a versão correta que esta testando e então escolher uma área sem cobertura. No caso da testfest deste ano, o PHPSP focou na GD pois sua cobertura estava bem baixa então navegamos até o gcov do gd.c para ver onde poderiamos atuar. Para fazer esta parte do processo um conhecimento básico de C e de como o PHP funciona por baixo dos panos é muito bom, mas após alguns testes você aprende a identificar os pontos e durante o testfest o Guilherme Blanco e o Erick nos ajudaram a entender o código.

Para exemplificar melhor vamos ver como identificar estas linhas e o que elas fazem. Veja por exemplo a linha abaixo:

O que queremos é que todas as linhas fiquem azuis (executadas) ou brancas (código não executável), as linhas não testadas estão marcadas de vermelho. Identificando a linha 1856 como não executada devemos interpretar que como há um if logo antes, a condição “== FAILURE” nunca é atingida, ou seja, esta linha nunca é executada pois a função zend_parse_parameters não retorna falso em nenhuma das chamadas a função imagecolorallocatealpha identificada logo ali encima na linha 1848.

Mas e ae? Ok, a função zend_parse_parameters é responsável por validar os parâmetros da função, ou seja, para testar esta função precisamos escrever alguns testes que passem parâmetros inválidos para a função e verifique se ela alerta o erro corretamente. Agora podemos passar para o passo de escrever este teste.

3. Escrevendo um teste

Escrever um teste é incrivelmente simples, e como testes devem ser objetivos e pontuais isso é bem claro. Você deve limitar o escopo de seu teste, procurando testar apenas uma função ou aspecto. Isso irá facilitar a nomeclatura de seu teste.

3.1 Nomeclatura de arquivos

A nomeclatura é bem simples:

• Teste para bug: bug.phpt
• Funcionamento básico da função: <função>_basic.phpt
• Erros da função: <função>_error.phpt
• Variação do funcionamento da função: <função>_variation.phpt
• Extensões: <extensão>_<#>.phpt

3.2 Estrutura de um .phpt

Arquivos de teste seguem uma estrutura bem simples:

--TEST--
strtr() function - basic test for strstr()
--FILE--
/* Do not change this test it is a README.TESTING example. */
$trans = array("hello"=>"hi", "hi"=>"hello", "a"=>"A", "world"=>"planet");
var_dump(strtr("# hi all, I said hello world! #", $trans));
?>
--EXPECT--
string(32) "# hello All, I sAid hi planet! #"

Como vemos, a sessão TEST é um título de uma linha do teste descrito no arquivo. A sessão FILE é usada como o corpo de um arquivo .php que será gerado para o teste, e a sessão EXPECT demonstra o resultado que esperamos da execução da função. Recomenda-se o uso de var_dump para gerar saídas.

Estas são sessões padrões, mas a documentação completa pode ser vista aqui: phpt format

Você poderá ver situações onde os blocos acima não são o bastante, mas em geral você estará checando para ver se executando a função X irá retornar a saída esperada. Porem um bloco é interessante ser mencionado aqui, o bloco CREDIT. Caso você não tenha acesso ao CVS, colocando seu nome nesse bloco irá levar seu nome aos créditos do PHP, no caso do TestFest utilizamos este formato:

--CREDIT--
Rafael Dohms <[email protected]> #PHPSPTestFest 2009-04-DD

Ok. Vamos tentar escrever um teste agora para ver se entendemos tudo até agora. Usando o exemplo acima onde identificamos uma linha não coberta por testes, vamos escrever um teste para testar o primeiro parâmetro da função. Observe a linha abaixo:

zend_parse_parameters(ZEND_NUM_ARGS() TSRMLS_CC, "rllll", &IM, &red, &green, &blue, &alpha)

O que devemos entender aqui é o trecho que diz “rllll” pois ele identifica o tipo que cada parâmetro deve ter, neste caso o primeiro parâmetro deve ser um “Resource” por isso o “r”, e os outros devem ser do tipo “long”. Pare um momento agora e verifique o manual do PHP para esta função

int imagecolorallocatealpha ( resource $image , int $red , int $green , int $blue , int $alpha )

Ele confirma exatamente o que vemos no código, mas você poderia também achar uma situação onde o manual esta incorreto, mais um ponto onde você poderia contribuir com o PHP.

Voltando ao nosso exemplo, vamos então escrever um teste para testar a validação do primeiro parâmetro da função. Verificando a pasta /ext/gd/tests vemos que não há testes desta função, mas especificamente não há um teste chamado imagecolorallocatealpha_error1.phpt, então como vamos testar justamente isto, podemos usar esse nome. (podemos usar _error2… para os outros parametros por exemplo)

--TEST--
Testing imagecolorallocatealpha(): Wrong types for parameter 1
--CREDITS--
Rafael Dohms <rdohms [at] gmail [dot] com>

Primeiramente vamos definir o título, deixando claro que estamos testando o parâmetro 1 da função e adicionar nosso crédito, que também é importante se houver algum erro no teste ou adaptação e precisarem saber quem foi o autor original do mesmo.

--SKIPIF--
<?php
if (!extension_loaded("gd")) die("skip GD not present");
?>

O bloco –SKIPIF– é muito importante neste caso. Como estamos testando uma função da GD, que é uma extensão do PHP, ela não estará sempre ativada, portanto só devemos executar os testes caso a extensão esteja ativa. O bloco SKIPIF é exatamente para isso, faça as verificações necessárias, caso não deva rodar, execute um die. O processo que executa os testes interpreta isso como SKIP e não FAIL. Isto vale para outras condições também, como arquivos necessários e qualquer outro fator que possa determinar se um teste deve ou não ser “pulado”.

--FILE--
<?php
$resource = tmpfile();

imagecolorallocatealpha($resource, 255, 255, 255, 50);
imagecolorallocatealpha('string', 255, 255, 255, 50);
imagecolorallocatealpha(array(), 255, 255, 255, 50);
imagecolorallocatealpha(null, 255, 255, 255, 50);
?>

Este é o corpo do teste, a parte mais importante. Basicamente estamos executando a chamada à função com diversos parâmetros inválidos, como strings, arrays e um resource que não é uma imagem. Passando um resource que não é imagem estamos na verdade testando a linha 1859, mas é uma condição importante de se testar também. O restante dos parâmetros recebem valores válidos.

--EXPECTF--
Warning: imagecolorallocatealpha(): supplied resource is not a valid Image resource in %s on line %d

Warning: imagecolorallocatealpha() expects parameter 1 to be resource, %s given in %s on line %d

Warning: imagecolorallocatealpha() expects parameter 1 to be resource, array given in %s on line %d

Warning: imagecolorallocatealpha() expects parameter 1 to be resource, null given in %s on line %d

Finalmente vamos testar o resultado. Aqui no caso utilizamos o EXPECTF que funciona como um printf, poderíamos ter usado outros disponíveis com expressões regulares por exemplo, mas o funcionamento deste é bem mais simples. Aqui basicamente estamos conferindo se o texto de erro bate com o que esperamos e como usamos um formato de printf $s e %d substituem textos que são dinâmicos, como o nome do arquivo que varia em cada máquina.

Dica: Para obter as mensagens de erro, rode o arquivos usando o PHP, ex: php imagecolorallocatealpha_error1.phpt. O arquivo será executado, todo conteudo dele será echoado na tela, mas dentro do bloco –FILE– o conteudo que aparecer é o resultado da execução.

4. Rodando um teste e fazendo faxina

Agora você tem um arquivo phpt pronto e precisamos ver se este teste esta mesmo passando. Para isso precisamos chamar o executor de testes e passar o nosso teste, caso contrário ele irá executar todos os 900+ testes. Para fazer isso o processo é simples, execute o comando make test da mesma forma de antes, mas definindo o parâmetro TESTS, assim:

make test TESTS=ext/gd/tests/imagecolorallocatealpha_*.phpt

Você pode dar o caminho completo para o arquivo, ou usar um wildcard como assim, isso é útil se você acabou de escrever os testes para todos parâmetros e quer rodar todos testes daquela função.

Veja o resultado:

Note que o teste passou, como indica o PASS logo em frente ao que escrevemos no bloco –TEST–. É interessante também comentar o que acontece quando um teste falha, além de ser marcado com um FAIL o sistema gera um numero de arquivos com o mesmo nome e diferentes extensões:

• .out - output do arquivo php criado po teste
• .php - o código gerado para o teste (bloco –FILE–)
• .diff - uma comparacao do que foi o output e do que se esperava
• .exp - o texto em –EXPECTEDF– isaolado
• .log - um resumo do processo

Estes arquivos são muito uteis para que se analise o resultado e poque da falha.

5. Enviado seu teste para o PHP

Você possui algumas formas de fazer seu teste chegar no PHP. A primeira é participando do PHPTestFest anual, onde todos os testes são enviados para um repositório separado e então integrados ao SVN oficial. A segunda forma é você enviar este teste que escreveu para a lista do QA Team e alguem irá colocar ele no SVN por você. A terceira forma é uma junção de ambas, muitas pessoas apos a testfest são presenteadas com contas do SVN e karma para poderem comitar seus próprios testes, como ocorreu comigo (viu, não é mentira!)

Conclusão

Pronto, agora você tem todas as ferramentas para começar a escreve testes para o PHP. O PHPT é excelente para sua função em testes do PHP, mas testes não param por ai, procure incluir os testes em seus sistemas e bibliotecas, mas para isso procure o PHPUnit e aprende sobre Test Driven Development (TDD). Em breve falarei destes por aqui também.