Using Data Provider Annotations in PHPUnit - Part1

Today, we are going to see “How to use Data Provider Annotations in PHPUnit”. Before entering into that topic, if you are new to PHPUnit, Please take a look my Previous Post, and then proceed reading this article. You can also find lot of PHPUnit Getting started guides available online by Googling.

Annotations:

As per PHPUnitManual, Definition for Annotations is:

An annotation is a special form of syntactic metadata that can be added to the source code of some programming languages“.

PHPUnit borrowed a handy featured from JUnit  Unit Testing Framework, called Annotations.

Annotations are meta information describing classes and its properties, methods or functions. They are always put in comments block above the code structure that they write.

The most common annotations that every PHP developer should know are the ones that used to document classes and their member properties. Annotation identifiers always start with a @ sign, there’s no other special rules associated on it.

While using annotations, you are making sure your code looks much more expressive and focusing on primary problem instead of writing lot of code.

Using Data Providers Annotations in PHPUnit

PHP usually lacks a way to parse the comments directly, so PHPUnit has its own tool that looks for certain phrases and characters to match in the comments. PHPUnit comes with list of annotations. Please refer to PHPUnitManual that contains the list of available annotations. Today, we will look how data provider annotations are being used in PHPUnit and what benefits it will provide for your application.

A Test Method in Test Case can accept arbitrary arguments, these arguments will be provided using dataprovider method.

These data provider method returns either array of array or an object that implements the Iterator interface and yields an array for each iteration. We will look each of one in details

Using Data Provider as Array of Array

Data provider method must be declared as public and method name doesn’t start with the word ‘test’. Let’s create a data provider method which will return array of array. This will become handy when you need to provide a series of different data sets to the test method.

PHPUnit will treat each array arguments as a different test and run the test method using the values of array returned from data provider method. This lets you check multiple sets of data against one test quite easily.

Class ContentTest  extends PHPUnit_Framework_TestCase{

    public function contentProvider()
    {
          return array(

              array(9,'phpmaster'),

              array(9,'sitepoint'),

              array(3,'php')

         );

    }
    /**
    * @dataProvider contentProvider
    */
    public function testContentLength($length, $string)

    {
      $this->assertEquals($length, strlen($string));

    }
}

From above code, the data provider method ‘contentProvider’ will be coupled with the test method ‘testContentLength’ using @dataProvider annotation. This data provider annotations will be added with the format ‘@dataProvider  <data provider name>’ under comments sections above the test method.

When I run the above test case in Zend Studio (By Right-Click File name, then select Run as => PHPUnit Test). Following is the test case result.

You will find the three passed test results that match with the three arrays values in data provider method. This Test method will check the length of the string using array values received as an arguments from data provider method, so  while running the first test, $length value will be ‘9’ and $string value will be 'phpmaster'. Using assertEquals, I am checking both $length value and the length of $string are Equals which is true so first test passes, similarly second and third test will also be passed.

In Next Post, Let's see how to use data provider Annotations as Iterator Object. Hope, you enjoyed this Post.