Simpletest Eclipse Plugin

Simpletest Eclipse Plugin Documentation

# compat Compatibility

- Operating System.
  This plugin should work on any platform on which Eclipse works. Specifically the plugin has been tested to work on Linux, OS X, and Windows. If the plugin does not appear to work on one of these platforms a new incompatibility may have emerged, but this is relatively unlikely.
- Eclipse
  The plugin has been designed to work with Eclipse versions 3.1.X+ and 3.2.X+. Eclipse in general requires a JVM version of 1.4.x; there are no additional requirements for the plugin.
- PHP
  The plugin has been tested to work with PHP 4.3.x+ (including PHP 5.1.x.).
- Xdebug
  The plugin can be configured to work with Xdebug (version 2.0.0RC1 or later). The php.ini file which is used by the plugin (see below for specifying the php.ini file) must load the Xdebug extension. This is usually accomplished by adding a zend_extension_ts="Some Windows Path" or zend_extension="Some Linux Path" to your php.ini file. Specific instructions can be found at: http://xdebug.org/install.php Do not worry about specifying any other parameters, the plugin will handle setting the necessary parameters, as needed.
- Simpletest
  The plugin has been designed to work with a specific version of Simpletest and in fact includes the associated version of Simpletest in the plugin for compatibility. A plugin with a version number of 1.0.0_0.0.4 would indicate that the plugin was compatible with Simpletest version 1.0.0 and was version 0.0.4 of the plugin. Some slight modifications to the Simpletest code are required to make the plugin work with Simpletest; these modifications may or may not be in the released version of Simpletest.
- PHPUnit2
  Starting with plugin version 0.1.6 experimental support for the CVS version of PHPUnit2 is available. To use PHPUnit2 select a path to PHPUnit2 and select PHPUnit2 test instead of SimpleTest. Note: this is the path to the folder that contains the PHPUnit2 folder. PHPUnit3 is not currently supported but will be supported in the near future.

# install Installation

1. Download and Install Eclipse (www.eclipse.org) – if you are not sure what to download, download the Eclipse 3.1.0 SDK.
2. Download the latest Simpletest Eclipse plug-in zip file (Simpletest Sourceforge)
3. Extract the zip file to a temporary location {this will be referred to later in this documentation as $unzip}
4. Start Eclipse
5. Open the Install Wizard by clicking "Help" > "Software Updates" > "Find and Install" from the menu bar.
6. Select the second button, "Search for new features to install" and click "Next".
7. Click the button on the right hand side, "New Local Site".
8. Select the folder $unzip {the folder extracted previously}.
9. Click the "OK" button.
10. In the "Edit Local Site" window, Click the "OK" button
11. Click the "Finish" button
12. In the "Search Results" window, drill down and select "Simpletest plug-in 0.0.x"
13. Click the "Next" button.
14. Read the license and accept the license by clicking the "I accept the terms in the license agreement" radio button and then clicking the "Next" button
15. In the "Installation" window you can choose to change the location -- most users should just click the "Finish" button
16. In the "Feature Verification" window, click the "Install" button.
17. When prompted, restart Eclipse

18. After starting Eclipse for the first time after installation you will need to perform a quick configuration of the Simpletest Plug-in. To perform this configuration:

    1. Select "Window" > "Preferences" from the menu bar
    2. Select "Simpletest" from the categories on the left hand side of the popup box.
    3. Enter or Browse for the location of a PHP executable to use.
    4. Leave the include file blank
    5. Enter .php as the Test File Suffix. Alternately if you name your test PHP files with a sufficiently different suffix (e.g sometest.tst.php) you could enter in a more differentiating suffix (e.g. .tst.php). This helps when the plug-in is looking for tests to execute.
    6. Hit the "Ok" button to close the preferences window.

# update Update Existing Installation

Note: this will only work if you have previously installed the plugin using the Eclipse installation wizard. If you previously copied directories for installation, it is recommended that you shutdown Eclipse, delete the previous version directories, and follow the Installation instructions above (you should not have to perform the initial configuration portion).

1. Select "Help" > "Software Updates" > "Manage Configuration" from the menu
2. Drill down to find the Simpletest plugin and select it
3. In the right hand pane click the link for "Scan for Updates"
4. IF no updates are found, navigate to Window > Preferences > Install/Update > Valid Updates in the Eclipse preferences and select 'Compatible', not 'equivalent'. Then repeat the steps above.
5. Select the feature versions that you wish to upgrade, and click "Next".
6. Review the license agreements for the upgraded features. If the terms of all these licenses are acceptable, check "I accept the terms in the license agreements." Do not proceed to download the features if the license terms are not acceptable.
7. Click "Install" to allow the downloading and installing to proceed.
8. Once all the features and plug-ins have been downloaded successfully and their files installed into the product on the local computer, a new configuration that incorporates these features and plug-ins will be formulated. Click Yes when asked to exit and restart the Workbench for the changes to take effect.

# uninstall Uninstall

Note: this will only work if the plugin was installed via the Feature Update method. If installed via alternate methods, then the plugin can be uninstalled by deleting the directories which were previously added.

1. Select "Help" > "Software Updates" > "Manage Configuration"
2. Drill down to find the Simpletest plugin
3. Right-click on the Simpletest plugin and select the option "Disable"
4. when prompted, restart Eclipse
5. After Eclipse has restarted, select "Help" > "Software Updates" > "Manage Configuration" from the menu bar
6. Select the option from the toolbar "Show Disabled Features"
7. Drill down to find the Simpletest plugin
8. Right-click on the Simpletest plugin and select the option "Uninstall"
9. When prompted, restart Eclipse

# usage Usage

The following details some sample usages of the plugin.

1. Create a new test project (a holding place for related files)
   1. Select "File" > "New" > "Project.." from the menu
   2. Expand the folder "General" and select "Project"
   3. Click the "Next" button
   4. On the next tab enter a project name: "Test"
   5. Use the default Project Contents
   6. Click the "Finish" button
2. Create a Single Passing Test
   1. In the Package Explorer View right-click on the "Test" project and select "New" > "File".
   2. For the filename enter: test1.php and click "Finish"
   3. Double-click on the test1.php entry in the Package Explorer which should open a new view to edit the file.
   4. Enter the following for the contents of the file: <?php class test1 extends UnitTestCase { function test_pass(){ $x = 1; $y = 2; $total = $x + $y; $this->assertEqual(3,$total, "This should pass"); } } ?>
   5. Select "File" > "Save" from the menu.
   6. Right click on the test1.php entry and select "Run" > "Run Simpletest".
   7. The "Result View" should populate with information about the test run and the Simpletest console should fill with some information as well.
3. Single Test class multiple tests
   1. In the Package Explorer View right-click on the "Test" project and select "New" > "File".
   2. For the filename enter: test2.php and click "Finish".
   3. Double-click on the test2.php entry in the Package Explorer which should open a new view to edit the file.
   4. Enter the following for the contents of the file: <?php class test2 extends UnitTestCase { function test_pass(){ $x = 1; $y = 2; $total = $x + $y; $this->assertEqual(3,$total, "This should pass"); } function test_fail(){ $x = 1; $y = 2; $total = $x + $y; $this->assertEqual(4,$total,"This should fail"); } } ?>
   5. Select "File" > "save" from the menu bar.
   6. Right click on the test2.php entry and select "Run" > "Run Simpletest".
   7. The Result View should populate with information about the test run and the Simpletest console should fill with some information as well
4. Group Tests (test multiple files at once)
   1. In the Package Explorer View right-click on the "Test" project and select "New" > "File"
   2. For the filename enter: grouptest.php and click "Finish".
   3. Double-click on the grouptest.php entry in the Package Explorer which should open a new view to edit the file.
   4. Enter the following for the contents of the file: <?php class myGroupTest extends GroupTest { function myGroupTest() { parent::GroupTest(''); $this->addTestFile(dirname(__FILE__).'/test1.php'); $this->addTestFile(dirname(__FILE__).'/test2.php'); } } ?>
   5. Select "File" > "save" from the menu
   6. Right click on the grouptest.php entry and select "Run" > "Run Simpletest"
   7. The Result View should populate with information about the test run and the Simpletest console should fill with some information as well

# known Known Issues

- Make sure that if a constructor is used in the test case that the last line of the constructor calls the parent constructor (e.g. parent::UnitTestCase)
- Do not put any assertions into the test class constructor
- If you get an error indicating that a class could not load; then restart Eclipse. Once Eclipse restarts, open the Result View manually by selecting "Window"->"Show View"->"Other..." Then select the SimpleTest Category and select "Result View" and click "OK".

# todo Future Features

These are features that should eventually make it into this plugin

- Allow different "include" file on each runner (override the "master" include)
- Handle fatal errors better

software development, eclipse plugin, php programming, programming php, software development tools, php tutorial, free php scripts, architecture, php resources, mock objects, junit, php testing, unit test, automated php testing, test cases tutorial, explain unit test case, unit test example, unit test