blob: e958363badc27dee7ae32532454682649190ad20 [file] [log] [blame]
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<!--Copyright (c) 2009, 2010, Oracle and/or its affiliates. All rights reserved.
-->
<html>
<head>
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
<meta name="description" content="How to integrate PHPUnit and Selenium with NetBeans IDE for writing automated tests. Includes demonstration of Code Coverage and the IDE's test result UI.">
<meta name="keywords" content="NetBeans, IDE, integrated development environment, tutorial, guide, user, documentation, open source, PHP, testing, automated testing, PHPUnit, Selenium, Code Coverage">
<link rel="stylesheet" type="text/css" href="../../../netbeans.css">
<title>Testing with PHPUnit and Selenium -- NetBeans IDE Tutorial</title></head>
<body>
<h1>Testing with PHPUnit and Selenium</h1>
<p>NetBeans IDE for PHP supports <a target="_blank" href="http://www.phpunit.de">PHPUnit</a> automated tests. Thanks to PHPUnit, NetBeans IDE provides code coverage for PHP, similar to the code coverage the IDE provides for Python. Test output appears in the same feature-rich output window that the IDE's JUnit and Python test runners use. </p>
<p>NetBeans IDE also supports the Selenium portable test framework, in combination with PHPUnit. A Selenium plug-in is available from the Update Center. Installing this plugin adds a Selenium server to the IDE's registered servers and adds Selenium test options to the PHP menus.</p>
<p><b>Contents</b></p>
<img src="../../../images_www/articles/73/netbeans-stamp-80-74-73.png" class="stamp" alt="Content on this page applies to NetBeans IDE 7.2, 7.3, 7.4 and 8.0" title="Content on this page applies to the NetBeans IDE 7.2, 7.3, 7.4 and 8.0" >
<ul class="toc">
<li><a href="#installing-phpunit">Installing PHPUnit</a></li>
<li><a href="#create-test">Creating and Running PHPUnit Tests</a></li>
<li><a href="#test-groups">Using Test Groups</a></li>
<li><a href="#result-windows">Test Results and IDE Output</a></li>
<li><a href="#code-coverage">Code Coverage</a></li>
<li><a href="#project-specific-configurations">Using Project-Specific Configurations</a></li>
<li><a href="#selenium">Running Tests on the Selenium Framework</a></li>
</ul>
<p><b>To follow this tutorial, you need the following software and resources.</b></p>
<table>
<tbody>
<tr>
<th class="tblheader" scope="col">Software or Resource</th>
<th class="tblheader" scope="col">Version Required</th>
</tr>
<tr>
<td class="tbltd1"><a target="_blank" href="https://netbeans.org/downloads/index.html">NetBeans IDE</a></td>
<td class="tbltd1">
PHP download bundle</td>
</tr>
<tr>
<td class="tbltd1">A PHP engine, including PEAR</td>
<td class="tbltd1">Version 5. </tr>
<tr>
<td class="tbltd1">A web server</td>
<td>Apache HTTP Server 2.2 is recommended.<br></td>
</tr>
<tr>
<td class="tbltd1"><a target="_blank" href="http://www.phpunit.de">PHPUnit</a></td>
<td>Version 3.4.0 or later.</td>
</tr>
<tr>
<td class="tbltd1"><a target="_blank" href="http://www.phpunit.de/manual/current/en/skeleton-generator.html">PHPUnit's Skeleton Generator</a></td><td>As version of PHPUnit.</td></tr>
</tbody>
</table>
<h2 id="installing-phpunit">Installing PHPUnit</h2>
<p>Use PEAR to install PHPUnit as described in the <a target="_blank" href="http://www.phpunit.de/manual/current/en/installation.html">PHPUnit documentation</a> and PHPUnit's Skeleton Generator as described in the <a href="http://www.phpunit.de/manual/current/en/skeleton-generator.html">Skeleton Generator documentation</a>. Install PHPUnit version 3.4.0 or later. No special setup is needed. After PHPUnit is installed, NetBeans can recognize it. Note that you need to have PEAR installed with your PHP engine. Also note that PHPUnit documentation says PHPUnit is usually installed to the local PEAR directory. They give a path of <tt>/usr/lib/php/PHPUnit</tt>, but on XAMPP for Windows it is <tt>XAMPP_HOME\php\PEAR\PHPUnit</tt>. </p>
<p>To check that NetBeans IDE recognizes your PHPUnit installation, open Tools &gt; Options (On Mac, open NetBeans Preferences) and look at the PHP window. Open the Unit Testing tab. The paths to your PHPUnit and Skeleton Generator scripts should appear. If a script is not there, click Search next to the empty field. The IDE searches you local system for the script. Alternatively, click Browse and browse for the script.</p>
<img src="../../../images_www/articles/72/php/phpunit/unittesting-options.png" height="477" width="600" alt="Options page showing path to PHPUnit script" class="margin-around">
<h2 id="create-test">Creating and Running PHPUnit Tests</h2>
<p>NetBeans IDE can create and run PHPUnit tests on all PHP classes in a file. To be sure that the test generator will work, give the PHP file the same name as the first class in the file. </p>
<p><strong>To create and run PHPUnit tests for a class:</strong></p>
<ol>
<li>Create a PHP project named Calculator. In this project, create a file named <tt>calculator.php</tt>. In this file, type or paste the Calculator class from the <a target="_blank" href="http://www.phpunit.de/manual/current/en/skeleton-generator.html">Skeleton Generator chapter of the PHPUnit documentation</a>.
<pre class="examplecode">&lt;?php
class Calculator
{
public function add($a, $b)
{
return $a + $b;
}
}
?&gt;</pre></li>
<li>Add a comment block with the <a target="_blank" href="http://sebastian-bergmann.de/archives/628-Improved-Skeleton-Generator-in-PHPUnit-3.html">@assert annotation</a> and some sample input and output. Note that one incorrect assertion is included in this example.
<pre class="examplecode">&lt;?php
class Calculator
{
/**
* @assert (0, 0) == 0
* @assert (0, 1) == 1
* @assert (1, 0) == 1
* @assert (1, 1) == 2
* @assert (1, 2) == 4
*/
public function add($a, $b)
{
return $a + $b;
}
}
?&gt;</pre>
<p class="notes"><strong>Note: </strong>You can use annotation code completion to add <code>@assert</code> annotations. Navigate between parameters with the Tab key, or click Enter after filling in a parameter value.</p>
<img src="../../../images_www/articles/72/php/phpunit/assert-cc.png" alt="Annotation code completion with @assert annotation" height="410" width="501" class="margin-around b-all"><img src="../../../images_www/articles/72/php/phpunit/assert-cc-complete.png" alt="Filling in parameters of the @assert annotation, using code completion" height="230" width="374" class="margin-around b-all"></li>
<li>In the Projects window, right-click the Calculator.php node and select Tools > Create PHPUnit Tests.
Note that you can create tests for all files in a project in the context menu for the Source Files node.<br>
<img src="../../../images_www/articles/72/php/phpunit/create-tests.png" height="647" width="453" alt="Context menu for Source Files node of PHP Project, showing Create PHPUnit Tests option" class="margin-around"></li>
<li>The first time you create tests, a dialog opens asking you for the directory in which you want to store test files. In this example, the Browse function was used to create a <tt>tests</tt> directory.
<br><img src="../../../images_www/articles/72/php/phpunit/test-directory.png" height="177" width="364" alt="Test file directory dialog" class="margin-around">
<p class="notes"><strong>Note:</strong> You can manually write multiple tests for a project. If you write multiple tests, you can sort them into subfolders of the test file directory, such as &quot;important&quot; or &quot;quick.&quot; You can then run tests in a subfolder by right-clicking that folder and selecting Run Tests.</p>
<img src="../../../images_www/articles/72/php/phpunit/test-in-folder.png" alt="Run Test folder context action" width="279" height="265" class="margin-around b-all">
</li>
<li>The IDE generates a skeleton test class in a file called CalculatorTest.php, which appears in your Projects window and opens in the editor.
<br><img src="../../../images_www/articles/72/php/phpunit/test-class-in-project.png" alt="Projects window showing new test class" height="245" width="204" class="margin-around">
<p>Note that a test is created for each <tt>@assert</tt> annotation.</p>
<pre class="examplecode"> /**
* Generated from @assert (1, 1) == 2.
*/
public function testAdd4()
{
$this->assertEquals(
2,
$this->object->add(1, 1)
);
}</pre></li>
<li>You can test either an individual file or the entire project. To test the project, right-click the project's parent node and select Test, or press Alt-F6. To test the Calculator.php file, right-clict the file's node and select Test, or press Ctrl-F6/&#8984;-F6. This example has only one class in one file, so the results are the same. The IDE runs the tests and displays the results in the Test Results window.
<br><img src="../../../images_www/articles/72/php/phpunit/test-results-narrow.png" alt="Test Results window" height="254" width="600" class="margin-around"> <p>A more verbose textual version of the results is displayed in the Output window.</p>
<img src="../../../images_www/articles/72/php/phpunit/test-result-output.png" alt="Output window showing test results" height="269" width="535" class="margin-around"></li>
</ol>
<h2><a name="test-groups"></a>Using Test Groups</h2>
<p>You can select which groups of tests to execute when the test suite is run. For example, you could have some tests you want to run only in a production environment and other tests that you want to run in both production and development environments. You would place the former tests in a <tt>production</tt> group and the latter tests in both <tt>production</tt> and <tt>development</tt> groups. When you run the test suite in your development environment, you select only the <tt>development</tt> test group to execute.</p>
<p>You must enable test groups for a PHP project before you use test groups on any file in that project. </p>
<p>To mark a test as part of a test group, annotate the test method with <tt>@group [group name]</tt>.</p>
<p><strong>To create and run test groups:</strong></p>
<ol>
<li>In the Projects window, right-click the Calculator node and select Properties. The Project Properties open.</li>
<li>In the Project Properties, select the PhpUnit category. Select Ask for Test Groups Before Running Tests. Click OK.<br><img src="../../../images_www/articles/72/php/phpunit/test-group-properties.png" alt="Project properties, PhpUnit category, showing test groups enabled" width="600" height="429" class="margin-around"></li>
<li>Open <tt>CalculatorTest.php</tt> in the editor.</li>
<li>For the methods <tt>testAdd</tt>, <tt>testAdd3</tt> and <tt>testAdd5</tt>, add the annotation <tt>@group production</tt>.<br><img src="../../../images_www/articles/72/php/phpunit/production-group-annotation.png" alt="Code showing test group annotation" width="391" height="155" class="margin-around b-all"></li>
<li>For the methods <tt>testAdd2</tt> and <tt>testAdd4</tt>, add the annotations <tt>@group production</tt> and <tt>@group development</tt>. <img src="../../../images_www/articles/72/php/phpunit/production-development-group-code.png" alt="Code showing test group annotations" width="388" height="172" class="margin-around b-all"></li>
<li>Right-click the <tt>Calculator.php</tt> node and select Test. A dialog opens, asking you which test groups to run. Select &quot;development&quot; and click OK. The IDE only runs the tests that are annotated with <tt>@group development</tt>.<br><img src="../../../images_www/articles/72/php/phpunit/select-test-group.png" alt="Select test group dialog" width="374" height="260" class="margin-around"></li>
</ol>
<p>For more information about PhpUnit test groups in NetBeans IDE, see the NetBeans IDE for PHP blog post <a target="_blank" href="http://blogs.oracle.com/netbeansphp/entry/using_phpunit_test_groups">Using PHP Unit Test Groups</a>.</p>
<h2 id="result-windows">Test Results and IDE Output</h2>
<p>The results of PHPUnit tests are displayed in two of the IDE's windows, Test Results and Output. The Test Results window has a graphic pane and a short text pane. The Output window gives a more verbose textual version of the output. In this section, you explore the Test Results and Output windows in detail.</p>
<p>In the Test Results window, you get information about failed tests from these locations:</p>
<ul>
<li>Messages in the UI pane attached to the tree entry for the failed test</li>
<li>Text in the right-side pane, including links to the lines of test code that failed</li>
<li>Tooltip text that appears when you hover the cursor over a failed test in the UI pane</li>
</ul>
<img src="../../../images_www/articles/72/php/phpunit/test-results-tooltip.png" class="margin-around" height="267" width="596" alt="Test results window showing tooltip">
<p>The Test Results window includes the following buttons on the left side:</p>
<ul>
<li> Rerun the test <img src="../../../images_www/articles/72/php/phpunit/rerun-button.png" alt="rerun button"></li>
<li>Show failed tests <img src="../../../images_www/articles/72/php/phpunit/show-failed.png" alt="Show failed tests button"></li>
<li>Show passed tests <img src="../../../images_www/articles/72/php/phpunit/show-passed.png" alt="Show passed tests button"></li>
<li>Show tests that passed but with errors <img src="../../../images_www/articles/72/php/phpunit/show-error.png" alt="Show tests with errors button"></li>
<li>Navigate between showing the next test result <img src="../../../images_www/articles/72/php/phpunit/next-test-button.png" alt="next test button"> or the previous test result <img src="../../../images_www/articles/72/php/phpunit/previous-test-button.png" alt="previous test button"></li>
</ul>
<p>The Output window shows the full output of the PHPUnit script. It can be useful when you cannot identify the cause of an error with the information in the Test Results window. Like Test Results, the Output window includes links to the test class line that failed. It also includes buttons on the left side for rerunning the test and for opening the PHP Options window. <img src="../../../images_www/articles/72/php/phpunit/options-link-button.png" alt="Button in Output window linking to Options"></p>
<img src="../../../images_www/articles/72/php/phpunit/test-result-output.png" alt="Output window showing full PHPUnit test results" height="269" width="535" class="margin-around">
<h2 id="code-coverage">Code Coverage</h2>
<p>NetBeans IDE for PHP offers code coverage along with PHPUnit support. (The IDE also offers code coverage for Python). Code coverage checks whether all your methods are covered by PHPUnit tests. In this section, you see how code coverage works with your existing Calculator class.</p>
<p><strong>To use code coverage:</strong></p>
<ol>
<li>Open Calculator.php and add a duplicate <tt>add</tt> function, called <tt>add2</tt>. The <tt>Calculator</tt> class now looks like the following:
<pre class="examplecode">&lt;?php
class Calculator {
/**
* @assert (0, 0) == 0
* @assert (0, 1) == 1
* @assert (1, 0) == 1
* @assert (1, 1) == 2
* @assert (1, 2) == 4
*/
public function add($a, $b) {
return $a + $b;
}
public function add2($a, $b) {
return $a + $b;
}
}
?&gt;
</pre></li>
<li>Right-click the project node. From the context menu, select Code Coverage > Collect and Display Code Coverage. By default, Show Editor Bar is also selected.
<br><img src="../../../images_www/articles/72/php/phpunit/turn-on-code-coverage.png" alt="Turning on code coverage from the project node context menu" height="251" width="503" class="margin-around" border="1"></li>
<li>The editor now has a code coverage editor bar across the bottom. Because code coverage has not been tested, the editor bar reports 0% coverage. (It also displays this after you click Clear to clear test results.)
<br><img src="../../../images_www/articles/72/php/phpunit/editor-bar-before.png" alt="Editor bar for code coverage before tests are run" height="428" width="592" class="margin-around"></li>
<li>Click Test to test the open file or All Tests to run all tests for the project. The Test Results display. In addition, the Code Coverage bar tells you what percentage of your executable code statements is covered by tests. In the editor window, covered code is highlighted in green and uncovered code is highlighted in red.
<p class="alert"><b>Warning: </b>If you re-generate the test files AFTER adding the add2 function, the PHPUnit tests will not run.
This is because PHPUnit creates two conflicting testAdd2 functions. Do not differentiate functions by appending numbers at the end if you plan to use PHPUnit on
more than one such function. See the <a href="http://www.phpunit.de/ticket/701" target="_blank">the PHPUnit documentation</a>. </p>
<img src="../../../images_www/articles/72/php/phpunit/editor-bar-after.png" alt="Editor bar for code coverage after tests are run" class="margin-around"></li>
<li>In the Editor Bar, click on Report... The Code Coverage report opens, showing the results of all tests run on your project. Buttons in the report let you clear the results, run all the tests again, or deactivate code coverage (click Done).
<br><img src="../../../images_www/articles/72/php/phpunit/code-coverage-report.png" alt="code coverage report" height="185" width="405" class="margin-around"></li>
<li>You can add another class to your project, delete and recreate the test files and look at the code coverage report again. Your new class is listed. In the following report, the <tt>Calculator</tt> class again has a function that is not included in the tests.
<br><img src="../../../images_www/articles/72/php/phpunit/code-coverage-report2.png" alt="code coverage report showing second class" height="226" width="451" class="margin-around"></li>
</ol>
<h2 id="project-specific-configurations">Using Project-Specific Configurations</h2>
<p>In the IDE, you can select the following custom configurations for your project:</p>
<ul>
<li>A bootstrap file</li>
<li>An XML configuration file</li>
<li>A test suite</li>
<li>A custom PHPUnit script</li>
</ul>
<p><strong>To set a project-specific configuration:</strong></p>
<ol>
<li>Right-click the project's node or the project's Test Files node and select Properties. This opens the Properties dialog.<br><img src="../../../images_www/articles/72/php/phpunit/project-ctxmenu.png" alt="Project context menu with Properties selected" width="330" height="427" class="margin-around"></li>
<li>Select the PHPUnit category. A dialog opens in which you can select a custom bootstrap, XML configuration, PHPUnit script, or test suite file.<br><img src="../../../images_www/articles/72/php/phpunit/proj-properties.png" alt="Project properties dialog, PHPUnit category" width="600" height="456" class="margin-around"></li>
<li>If you are not familiar with the structure of bootstrap or XML configuration files, you can use NetBeans IDE to generate a skeleton for you. You can also find instructions about using the dialog by clicking Help. <br><img src="../../../images_www/articles/72/php/phpunit/proj-properties-selected.png" alt="Project properties, PHPUnit category, details" width="379" height="423" class="margin-around"></li>
</ol>
<p>The <em>bootstrap option</em> is required for projects that use a custom class loader, for example by implementing the <tt>__autoload()</tt> magic function. You also use the bootstrap option if you need to include a file in advance, such as a file that defines global constants used by multiple classes in your project.</p>
<p>The <em>XML configuration file</em> allows you to define options that you use in a command line call. There is a complete introduction in the <a target="_blank" href="http://www.phpunit.de/manual/3.3/en/appendixes.configuration.html" title="PHPUnit Manual">PHPUnit manual</a>. You can also use the XML configuration file to define <tt>php.ini</tt> settings and global vars for your test cases. You can set the bootstrap option in the XML configuration file too.</p>
<p>If you set a <em>custom test suite,</em> you run that suite whenever you select Run &gt;Test Project. This is particularly useful when you wish to run only a subset of your tests, or if you want to use recently added features of PHPUnit that you have to add manually, such as Data Providers. Note that you may of course define as many test suites as you want and run them separately by right-clicking the file in your project explorer and choosing "run". To prevent confusion, NetBeans notifies you if you are using a custom Test Suite. The notification can be found in the Test Results and in the Output window.</p>
<p>You can use a <em>custom PHPUnit script</em> for a project, instead of the default script selected in Tools &gt; Options. The custom PHPUnit script can include any command-line switches described in the <a href="http://www.phpunit.de/manual/3.7/en/textui.html">PHPUnit manual</a>.</p>
<p>&nbsp;</p>
<h2 id="selenium">Running Tests on the Selenium Framework</h2>
<p>Selenium is a portable software testing framework for web applications. The tests can be written as HTML tables or coded in a number of popular programming languages and can be run directly in most modern web browsers. Selenium can be deployed on Windows, Linux, and Macintosh. For more details see the <a target="_blank" href="http://docs.seleniumhq.org">Selenium web site</a>. </p>
<p>NetBeans IDE has a plugin that includes a Selenium server. With this plugin, you can run Selenium tests on PHP, Web Application, or Maven projects. To run Selenium tests on PHP, you need to install the Testing Selenium package to your PHP engine.</p>
<p><strong>To run Selenium tests on PHP:</strong></p>
<ol>
<li>Open a command prompt and run the command <tt>pear install Testing_Selenium-beta</tt>. You need<tt> PHP_HOME/php/PEAR</tt> on your Path. If the command is successful, the prompt will display <tt>install ok: channel://pear.php.net/Testing_Selenium-0.4.3</tt>.</li>
<li>In the IDE, open Tools &gt; Plugins and install the Selenium Module for PHP.</li>
<li>In the Projects window, right-click the project node for your Calculator project. Select New &gt; Other. The New File wizard opens. Select Selenium and click Next.
<br><img src="../../../images_www/articles/72/php/phpunit/new-selenium.png" height="413" width="543" alt="New File wizard with Selenium file chosen" class="margin-around"></li>
<li>The first time you create a Selenium test, a dialog opens asking you to set a directory for Selenium test files. This should be a separate directory from PHPUnit test files. Otherwise, the Selenium tests run every time you run unit tests. Running functional tests like Selenium usually takes more time than running unit tests, therefore you will probably not want to run these tests every time you run unit tests.</li>
<li>Accept the defaults in the Name and Location page and click Finish. The new Selenium test file opens in the editor and appears in the Projects window.
<br><img src="../../../images_www/articles/72/php/phpunit/selenium-test-in-project.png" alt="Projects window showing new Selenium test" height="187" width="279" class="margin-around"></li>
<li>The Run Selenium Tests item is now added to the project's context menu. Click this item, and the Selenium test results display in the Test Results window, the same as PHPUnit tests.</li>
</ol>
<h2 id="more-exercises">More Exercises</h2>
<p>Here are a few more ideas for you to explore:</p>
<ul>
<li>Add a second class to Calculator.php, such as a <tt>Calculator2</tt> class that multiplies $a and $b. Delete and regenerate the tests.</li>
<li>If you try the multi-part <a href="./wish-list-tutorial-main-page.html">Creating a CRUD Application tutorial</a>, create a Selenium test for the final project. </li>
</ul>
<div class="feedback-box">
<a href="/about/contact_form.html?to=3&amp;subject=Feedback:PHPUnit and Selenium on NB 6.7">Send Feedback on This Tutorial</a>
</div>
<br style="clear:both;" >
<p>To send comments and suggestions, get support, and keep informed on the latest
developments on the NetBeans IDE PHP development features, <a href="../../../community/lists/top.html">join
the users@php.netbeans.org mailing list</a>. This list is mirrored on the <a target="_blank" href="http://forums.netbeans.org/">NetBeans IDE forums</a>.</p>
<a name="seeAlso"></a>
<h2>See Also</h2>
<p>For more information about testing PHP in NetBeans IDE<a target="_blank" href="https://netbeans.org/"></a>,
see the following resources:</p>
<ul>
<li><a target="_blank" href="http://blogs.oracle.com/netbeansphp/entry/phpunit_support_added">NetBeans for PHP Blog: PHPUnit Support Added</a></li>
<li><a target="_blank" href="http://blogs.oracle.com/netbeansphp/entry/ui_for_phpunit_support">NetBeans for PHP Blog: UI for PHPUnit Support</a></li>
<li><a target="_blank" href="http://blogs.oracle.com/netbeansphp/entry/code_coverage_for_php_why">NetBeans for PHP Blog: Code Coverage for PHP -- Why Not?</a></li>
<li><a target="_blank" href="http://blogs.oracle.com/netbeansphp/entry/recent_improvements_in_phpunit_support">NetBeans for PHP Blog: Recent Improvements in PHPUnit Support</a></li>
<li><a target="_blank" href="http://wiki.netbeans.org/SeleniumPluginPHP">NetBeans IDE Wiki: Selenium Plugin for PHP</a></li>
<li><a href="./debugging.html">Debugging PHP Source Code in the NetBeans IDE</a></li>
</ul>
<p><a href="../../trails/php.html">Back to the PHP Learning Trail</a> </p>
</body>