Story: http://www.infoq.com/news/2008/05/WSMock

Introduction

WSO2 Web services Framework for PHP is the richest Web services platform in the PHP world. When you are developing industry standard  Web services using WSO2 WSF/PHP, it is really important to test it thoroughly to ensure that it works. Developing large systems always leads us to maintain a huge number of  test cases.  These test cases should be organized in a way that they are easy to manage.  PHPT  brings with it the perfect solution to this concern.

Applies To 

Table of Contents

1. The Problem
2. The Solution
3. Web service Implementation
4. Testing, The Tough Bit
5. Summary

The Problem

When you do serious business online with WSO2 WSF/PHP Web services, its really important to test your Web service thoroughly to make sure that it does exactly what you expect it to do - and does only that! You always need to test all the success cases as well as the failures too. When you make an improvement to your Web service, you always have to make sure that the existing functionality is not broken by with the new changes introduced. The best way to achieve this goal is to maintain a set of carefully designed test cases that are organized in a way that you can very easily run them and see their results. Also you need to be able to add new test cases very easily. But what if you can run the entire set of test cases from a single command? And what if you can, obtain a short and sweet log file with details of passed and failed test cases? 

The Solution

To achieve these objectives, the best option is an automated test framework where you can define a test suite with all different test cases you want to test your system with. Almost all the test frameworks you can find out there are designed in a way that the user can maintain his/her test cases in a very organized manner. User can add new test cases very easily. At the end of the test run, the framework generates a very easy to understand report, which has the details of passed test cases as well as the failed test cases.
PHP's phpt is such a test framework that you can use to test WSF/PHP Web service. It has all the capabilities that you can use to solve your Web services testing concerns.
Throughout the following sections of this article, I'll guide you on how to build a very effective test suite to test your WSO2 WSF/PHP Web service. Stay tuned...

Web Service Implementation

Consider the following simple Web service. It takes two integers from user as input parameters and returns the division of the two values. Imagine that the original requirement specification of the Web service states that the service should return an error message as "division by 0" if the second input parameter is zero (0), but that the developer forgot to implement it.  

<?php

/*
 * div_service.php
 * Simple WSF/PHP web service
 * Gets 2 integers
 * Divide the first by second and return the result.
 * If the division by 0, send a fault saying "A division by 0". This is NOT implemented yet
 */

function divFunction($inMessage) {

    
    $simplexml = new SimpleXMLElement($inMessage->str);
    $value1 = $simplexml->param1[0];
    $value2 = $simplexml->param2[0];
    $Result = $value1 / $value2;    
    
    $resPayload = <<<XML
        <ns1:result xmlns:ns1="http://ws.axis2.org/axis2/php/math">$Result</ns1:result>
        XML;
    
    $returnMessage = new WSMessage($resPayload);
    return $returnMessage;
}

$operations = array("div" => "divFunction");
$svr = new WSService(array("operations" => $operations));
$svr->reply($reqPayloadString);

?> 

Save the above php script in a file called div_service.php and deploy it with WSF/PHP. Read this article for more information on WSO2 WSF/PHP Web services.

Testing, The Tough Bit

Now, you have a Web service deployed. Its time to start testing it. Here, I'll discuss two simple test cases. Our first test case will send two integer values (10 and 5) to the Web service and expect an integer ( 5 ) as the result. Our second test case will test the division by zero case. When you design test cases there are so many factors that you need to consider in order to decide which test data are used. But that piece of theory is out of the scope of this article. The values I've used here are just to demonstrate our main subject.

Let's look at the basic structure of a phpt test case.

--TEST--
   Description of the test case goes here
--FILE--
<?php 
   Your test client written in php
?>
--EXPECT--
Expected output of the above php script

This is the basic structure of a simple phpt test case. As the description, the test file name and a simple discription of the test case are given. Under the '--FILE--' section, the php test script is placed. phpt test framework will execute this script and obtain the result and compare it with expected results specified in the --EXPECT-- section of the test case. If the actual result are identical to the expected value, the framework will log the test result as PASSED, FAILED otherwise.
So, Lets start writing our first test case according to this structure. This test case will pass two non-zero integers 10 and 5 to the service and expects it to return 2.
We'll give the name of the test file and a simple description of the test case in the --TEST-- section.

--TEST--
Testcase1.phpt - Parses two non-zero values

In the --FILE-- section, we will write a simple web service client which passes 10 and 5 to the web service and display the result.

--FILE--
<?php
$reqPayloadString = <<<XML
<ns1:div xmlns:ns1="http://ws.apache.org/axis2/php/math">
     <param1>10</param1>
     <param2>5</param2>
</ns1:div>
XML;

     try
     {
        $client = new WSClient(array(
                      "to"=>"http://localhost/samples/div_service.php"));
        $response = $client->request($reqPayloadString);

        if ($response)
        {
            $simplexml = new SimpleXMLElement($response->str);
            $value1 = $simplexml;
            printf("Response = %s \n", $value1);
        }
     } 
     catch (Exception $e)
     {
        if ($e instanceof WSFault)
        {
         printf("Soap Fault: %s\n", $e->Reason);
        }
        else
        {
         printf("Message = %s\n",$e->getMessage());
        }
     }

?>

Our expected result is:
Response = 2
We'll put this in the --EXPECT-- section as follows.

--EXPECT--
Response = 2

Now, lets save our new test case in a file called Testcase1.phpt. Please note that when you develop real test cases, you need to make sure to give them meaningful names. Your test case should look like the following:

--TEST--
Testcase1.phpt - Parses two non-zero values
--FILE--
<?php
$reqPayloadString = <<<XML
<ns1:div xmlns:ns1="http://ws.apache.org/axis2/php/math">
     <param1>10</param1>
      <param2>5</param2>
</ns1:div>
XML;
     try
     {
        $client = new WSClient(array(
                      "to"=>"http://localhost/samples/div_service.php"));
        $response = $client->request($reqPayloadString);
        if ($response)
        {
            $simplexml = new SimpleXMLElement($response->str);
            $value1 = $simplexml;
            printf("Response = %s \n", $value1);

        }
     } 
     catch (Exception $e)
     {
        if ($e instanceof WSFault)
        {
          printf("Soap Fault: %s\n", $e->Reason);
        }
        else
        {
          printf("Message = %s\n",$e->getMessage());
        }
     }
?>
--EXPECT--
Response = 2

Now, Lets try to run and see this test case. To run the test cases we use a utility tool called 'pear' that comes with the php distribution. Please refer php documentation for additional information on pear. To run your test case, go to the folder in which you saved your Testcase1.phpt file from the command prompt. Now, run the following command.

pear run-tests

you can now see the test results in the command prompt:

Running 1 tests
PASS Testcase1.phpt - Parses two non-zero values[Testcase1.phpt]
TOTAL TIME: 00:05
1 PASSED TESTS
0 SKIPPED TESTS

You can see that the framework shows your test case passing.
Now, lets try to implement another test case. In this, we send 10 and 0 as parameters and expect the service to return a fault message as "Division by 0". Our new test case should look like the following.

--TEST--
Testcase2.phpt - Parses 10 and 0 and expects a divition by 0 fault
--FILE--
<?php
$reqPayloadString = <<<XML
<ns1:div xmlns:ns1="http://ws.apache.org/axis2/php/math">
     <param1>10</param1>
      <param2>0</param2>
</ns1:div>
XML;
     try
     {
        $client = new WSClient(array(
                      "to"=>"http://localhost/samples/div_service.php"));
        $response = $client->request($reqPayloadString);
    
        if ($response)
        {
            $simplexml = new SimpleXMLElement($response->str);
            $value1 = $simplexml;
            printf("Response = %s \n", $value1);

        }
     } 
     catch (Exception $e)
     {
        if ($e instanceof WSFault)
        {
         printf("Soap Fault: %s\n", $e->Reason);
        }
        else
        {
         printf("Message = %s\n",$e->getMessage());
        }
     }
?>
--EXPECT--
Soap Fault: A division by 

Please note the param2 of the reqPayloadString is now 0 and the expected value is also chenged to the fault string we expect to receive. Now, save this file as Testcase2.phpt, to the same location you saved Testcase1.phpt and run 'pear run-tests' on the command line. Now you can see that the framework executes both the test cases and display the results as follows.

Running 2 tests
PASS Testcase1.phpt - Parses two non-zero values[Testcase1.phpt]
FAIL Testcase2.phpt - Parses 10 and 0 and expects a divition by 0 fault[Testcase2.phpt]
wrote log to "C:\KB\run-tests.log"
TOTAL TIME: 00:06

1 PASSED TESTS
0 SKIPPED TESTS
1 FAILED TESTS:
C:\KB\Testcase2.phpt

You can notice that one test case is now failing. The framework lists at the bottom of the report, the test file which is failing. It is Testcase2.phpt. Now lets find the reason for this failure. You can find a log file of this test case in the folder where the test file resides. Go to your test folder and open the file Testcase2.log. The contents of this file is as follows.

---- EXPECTED OUTPUT
Soap Fault: A division by 0
---- ACTUAL OUTPUT
Message = Error , NO Response Received
---- FAILED

Here you can see that the actual output of the test case is different from the expected output, hence the test case has failed. It seems that our Web service does not bahaves as expected. That means the Web service contains a bug. So lets edit the our Web service according to the requirement. We will change the divFunction of our service in a way that it checks the second parameter, and for it to return a wsfault if it was a zero.

Following is our editted divFunction:

function divFunction($inMessage) {
    $simplexml = new SimpleXMLElement($inMessage->str);
    $value1 = $simplexml->param1[0];
    $value2 = $simplexml->param2[0];
    if($value2 == 0)
    {
        throw new WSFault("Sender", "A division by 0");
    }
    else {
    $Result = $value1 / $value2;    
    $resPayload = <<<XML
<ns1:result xmlns:ns1="http://ws.axis2.org/axis2/php/math">$Result</ns1:result>
XML;
    }

    $returnMessage = new WSMessage($resPayload);
    return $returnMessage;
}

Now, deploy your modified service and run your test suite again to verify that the changes are effective. Simply run the command 'pear run-tests' on the command prompt to do:

Running 2 tests
PASS Testcase1.phpt - Parses two non-zero values[Testcase1.phpt]
PASS Testcase2.phpt - Parses 10 and 0 and expects a divition by 0 fault[Testcase2.phpt]
TOTAL TIME: 00:06
2 PASSED TESTS
0 SKIPPED TESTS

Congratulations! Your Web service is now working. You can run as many test cases as you wish to test your your Web service in this manner. It will help you build a very efficient and accurate Web service.

Summary

In this article we discussed how we can use PHP's regression test framework, referred to as 'phpt', to test our WSF/PHP Web service. We demonstrated a simple Web service written in php and  two simple phpt test cases to test that service. You can download the sample scripts used in this article from the link given below:

Author

Dushshantha Chandradasa,  Senior Software Engineer, Quality Assurance. dushshantha at wso2 dot com