How to Contribute to PHP Development Writing phpt Tests

Contents

Introduction

What is the phpt Test Format?

What Skills are Necessary to Write a phpt Test?

How to Start Writing phpt Tests?

Structure of the phpt file

Writing .phpt Tests and Contribute to PHP Core Development

Are you ready to Help? Then Go!

How do you know if a .phpt test worked?

What is the best way to write a good test?

Scripts to generate test reports

What is PFTT?

.phpt good pratices

Conclusion

Introduction

There are several types of tests for various purposes, behavior, integration, among others, but when we talk about writing tests, always with an application in mind, let's see how we can write tests using phpt format files.

What is the phpt Test Format?

A phpt test is a little script used by PHP core developers and the QA (Quality Assurance) teams to test the features of PHP. It can be used with new releases to assure that those PHP features continue working as in previous versions. These tests can also help finding bugs in current versions.

What Skills are Necessary to Write a phpt Test?

So if you have written and run PHP scripts, you have everything you need.

How to Start Writing phpt Tests?

The phpt tests files follow a very strict naming convention. This is done to easily identify what each phpt test does. The tests should be named according to the following list:

Test for bugs

Here is an example of a reported bug and an example of a bug file .phpt written to ensure that this bug this fixed correctly.

Test for a basic behavior of the function

Here is an example of a basic test

Test for a function with error

Test for the variation of a function

In this case, is when we want to perform various types of tests, more beyond _ basic. phpt, in this case we have the option to test variations. So we write a test case in a file <functionname> _ variation1. phpt. Another type of test case in another file <functionname> _ variation2. phpt and so on as in the examples below:

array_change_key_case_variation.phpt

array_change_key_case_variation1.phpt

array_change_key_case_variation2.phpt

array_change_key_case_variation3.phpt

array_change_key_case_variation4.phpt

array_change_key_case_variation5.phpt

Tests for Extensions

This type of test is used to test for extensions of PHP. Its naming convention is <extname> <no> .phpt . Here is an example of a test for broker. Here example for the mysqli extension.

Structure of the phpt file

For a complete list of all the tags that you can use to to write phpt scripts, check here.

--TEST--

--SKIPIF--

<?php
if (PHP_INT_SIZE != 4) die("skip this test is for 32bit platforms only");
?>

--CREDITS--

marcosptf - <marcosptf@yahoo.com.br>
#phptestfest PHPSP on Google - Sao Paulo - Brazil - 2014-06-05

--FILE--

<?php
/* 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! #"

--EXPECTF--
test result when in float values
string(3) "%s"

--EXPECTREGEX--
test result when in regex values
string\(18\) \"nica\x00turska panica\"
string\(19\) \" nica\x00turska panica\"

Now let's apply these concepts to write tests in the official PHP core project.

This is the project that takes care of the main source code of the PHP language, reviews, new features, merge from branches, application of bug fixes, among other things.

I'm sure if you have been programming PHP a while, you already have a notion of this.

PHP is a programming language with the source code open to open source community. Anyone who has interest to help can go in the project pages, download the source, study it, correct, change and propose improvements.

Who takes care of the project are volunteers, people like us who offers a part of his time to commit changes, perform merges of pull request sent, answer some questions of open bugs among other things. There are also the architect heads, which in some cases work for Zend.

In a project of this size and global reach, there are numerous people reporting bugs and creating pull requests all the time, but the number of reviewers is very limited.

If you consider yourself an expert programmer, why not take a few minutes of your time to help PHP getting better? Remember that you used it until today to study and work.

Contributing to the project, is nothing more than saying, "thank you" to the open source community who worked days and nights with the goal to leave the project in a level of maturity that is so great that today it is used and respected by large companies and corporations.

Are you ready to Help? Then Go!

You can write a test for a function of the language basically speaking, a string function, or an array function, or a function provided by one of the countless PHP extensions, a mysqli function, or an image, or a mcrypt function, etc...

You can find the functions that already have phpt tests looking at the HTML version git repository. ext/standard/tests/ is a good place to start looking, though not all the tests are currently there.

If you look at the gcov pages you can see which functions have lots of tests and which need more, although these pages only show which lines of code are covered by test cases.

Even if the coverage information is correct, it can be interesting to have more tests, for example to cover more error cases.

There is also a table that shows which functions and methods are called from PHPT tests.

Look here where you can get a complete list of general coverage of the gcov.

Now if you want to show function tests, is more objective to look if there is any test without coverage or if you want to maintain the tests that failed and help PHP QA to make tests more resilient.

If you want now you can view the project php-src Jenkins and see how is this project status in the different PHP versions.

How do you know if a .phpt test worked?

When a test is called by the run_tests.php, a script takes the various parts of the phpt file to
name and create a .php file. This .php file is executed then. The output of the .php file is then compared with a different section of the phpt file. If the output of the script "matches" the output provided in the .phpt file script, it passed.

What is the best way to write a good test?

After writing the test case, use preferably the phpunit to see if this test pass. Create a fork from php-src project on github.

Create a new branch and perform the commit to that branch. Head over to github and click the option to make a pull request. Your submission will appear here.

Once the pull request sent, Travis-ci kicks in. That is responsible for checking if the branch you submitted will not conflict as rest of the project.

Here follows an example created by Travis-ci containing errors of a branch.

Be patient until a core developers will look at your pull request and verifies that your commit is approved to be integrated.

Scripts to generate test reports

The run-tests.php script is the standard tool for running tests in the PHP core based on .phpt on the command line (CLI scenario). Whenever users compile PHP from the source, they must run ' make test ', whcih executes the run-test.php script on your PHP environment.

What is PFTT?

PFTT covers the PHP ecosystem and is designed for convenience and speed.

PFTT, PHPT and PHPUnit tests can run through a variety of scenarios, including in Apache.

.phpt good pratices

Don't forget to perform, commits, creation of branch and submit pull request messages in English, because the core of the project commiters are from different countries around the world, and the English is what we use to communicate.

Conclusion

Nowadays PHP is a language with a complex feature set. There is no shortage of aspects that need to be test so PHP becomes a much bug free as possible.

This article provide a nice introduction to create tests using the .phpt so now you should be ready to also help PHP development by adding much needed tests where they are still lacking.

If you like this article, please share it. If you have a question about PHP tests, post a comment to this article.