MakeGood User Guide¶

This user guide describes MakeGood 1.9.0, 1.8.0, and 1.7.0

English | 日本語

• MakeGood User Guide
  • Installation
    • Installing Prerequisite Software
    • Installing MakeGood
    • Configuring a PHP Executable
    • Configuring Your Workspace and Projects
  • Running Tests
    • Runs tests when a file is saved. (Autotest)
      • Runs all tests when a file is saved.
      • Runs the last test when a file is saved.
    • Runs all tests.
      • Runs all tests from the PHP Explorer, Package Explorer, Outline, and other views.
      • Runs all tests from the PHP Editor.
    • Runs tests from the PHP Explorer, Package Explorer, Outline, and other views.
    • Runs tests from the PHP Editor.
    • Debugs a test.
    • Reruns the last test.
    • Stops the test run.
    • Stops on the first failure or error.
  • Analyzing Test Results
    • Tracks failures and errors.
    • Tracks a fatal error.
    • Displays the last test result in the status bar.
  • Configuration
    • Selecting the default value for the feature "Run tests when file is saved"
    • Using the System Include Path
    • Using a Preload Script
    • Selecting a Testing Framework
    • Resolving the Dependencies to the Testing Framework
      • Defining User Libraries
      • Adding User Libraries to the Project
    • Specifying the Test Folders
    • Key Bindings
      • The Default Key Bindings
  • Testing Framework Specific Configuration
    • PHPUnit
      • Configuring the PHPUnit Runtime Environment by the XML Configuration File
    • CakePHP
      • Specifying the Path of your App Folder
      • Specifying the Path of your CakePHP Libraries Folder
    • CIUnit
      • CIUnit tests directory
      • Configuring the PHPUnit Runtime Environment by the XML Configuration File
  • Notes
    • The Conventions for Test Files
    • The Console View and Focusing
  • Known Issues
    • A test session is not terminated.
    • A key binding conflicts with "Undefined Command".
    • Additional INI files are not loaded.
    • Relative paths in a PHPUnit XML file do not work.
    • No output to the Debug Output view when running a test with Xdebug.
    • Can't add nested directories to the include path.

Installation¶

Installing Prerequisite Software¶

The following software are required to run MakeGood.

• PHP 5.2.0 or greater
• Zend Debugger or Xdebug
• Eclipse Indigo (3.7) or Eclipse Helios (3.6)
• PDT 3.0 or 2.2
• (optional) Stagehand_TestRunner 2.20.0 or greater
• (optional) PHPUnit 3.4.1 or greater
• (optional) SimpleTest 1.0.1 or greater
• (optional) CakePHP 1.3 or 1.2
• (optional) CIUnit v0.17

Install these software refer to the following sites:

• PDT/Installation
• Xdebug: Documentation
• Eclipse PHP Development Tools - Zend.com
• Stagehand_TestRunner - A test runner for Test Driven Development - Piece Framework
• Chapter 3. Installing PHPUnit
• Preparing for testing :: Testing :: Common Tasks With CakePHP :: The Manual :: 1.3 Collection :: The Cookbook

NOTE: Zend Debugger for PHP 5.3 is included in Zend Server Community Edition.

NOTE: Also take a look at the known issue Can't add nested directories to the include path.

NOTE: PDT for Eclipse Helios SR2 have some critical defects including the defect that caused the Toggle Comment command not to work. These defects can fix by replacing some plugins with Patched plugin for eclipse-php-helios-SR2.

Installing MakeGood¶

First, launch your Eclipse and select Help -> Install New Software... from the menu bar. Next, click the Add... button and register the following update site:

Name	An arbitrary string or empty
Location	http://eclipse.piece-framework.com/

And, select the feature of MakeGood and click the Next > button.

Next, click the Finish button. Therefore, the installation is started. The dialog for the certificate will be displayed in the middle of the installation process, click the Select All button, and click the OK button.

When the installation is completed, the dialog will be displayed that recommends to restart Eclipse, and click the Yes button. Therefore, Eclipse is restarted and the installation is done.

Configuring a PHP Executable¶

Since MakeGood uses a PHP executable which is already defined in PDT, you should configure at least one PHP executable.

First, select Window -> Preferences... from the menu bar, and select PHP -> PHP Executables. Next, click the Add... button and configure a PHP executable.

Next, click the Finish button, and select PHP -> Debug from the side menu. Next, configure Default Settings as the following:

PHP Debugger	Zend Debugger or XDebug
Server	(any)
PHP Executable	(A PHP executable you want to use.)

Configuring Your Workspace and Projects¶

You must configure your workspace and projects properly before starting to use MakeGood.

Getting MakeGood to work, at least you select a testing framework for your project, and must resolve the dependencies to the testing framework.

For more information, see Selecting a Testing Framework and Resolving the Dependencies to the Testing Framework in the Configuration chapter.

Running Tests¶

NOTE: Also take a look at The Conventions for Test Files.

NOTE: If your Eclipse context go out of the scope of your Eclipse projects (e.g. external files), the last valid context will be used instead of the current context.

Runs tests when a file is saved. (Autotest)¶

NOTE: Whether how this feature works by default is determined by the value of the configuration parameter Selecting the default value for the feature "Run tests when file is saved".

Runs all tests when a file is saved.¶

NOTE: To enable this feature, test folders should be specified in project properties. For more information, see Specifying the Test Folders.

Runs all tests automatically when a file is changed/added/removed in the workspace. If a file is changed outside of the workspace, run tests when the workspace is synchronized.

To enable this feature, click the Run All Tests when File is Saved button on the MakeGood view so that the button is pushed in.

Runs the last test when a file is saved.¶

Runs the last test automatically when a file is changed/added/removed in the workspace. If a file is changed outside of the workspace, run tests when the workspace is synchronized.

To enable this feature, click the Run Last Test when File is Saved button on the MakeGood view so that the button is pushed in.

Runs all tests.¶

NOTE: To enable this feature, test folders should be specified in project properties. For more information, see Specifying the Test Folders.

Runs all tests which are included in the specified test folders.

Runs all tests from the PHP Explorer, Package Explorer, Outline, and other views.¶

Selects any resource in the PHP Explorer/Package Explorer/Outline/other views and runs all tests.

To run all tests, select a resource, and select Run all tests from the context menu.

Runs all tests from the PHP Editor.¶

Runs all tests from the active editor.

To run all tests, do right click in the editor, and select Run all tests from the context menu.

Runs tests from the PHP Explorer, Package Explorer, Outline, and other views.¶

Selects one or more resources in the PHP Explorer/Package Explorer/Outline/other views and runs tests.

To run tests, select resources, and select Run Tests from the context menu.

After the test run is done, the test results are displayed to the MakeGood view.

The following resources are available:

• Folder
• File
• Class (PHP Explorer only)
• Method (PHP Explorer only)

NOTE: The dialog to select the preload script is displayed only when it is the first time that you run tests in the project. The preload script makes preparations for a test run, which are the include path, autoloading, and error handling, etc. It is evaluated before the test runner body is loaded. If you do not use the preload script, leave empty and click the OK button. For more information, see Using a Preload Script.

Runs tests from the PHP Editor.¶

NOTE: The dependencies of the current editing file should be resolved on Eclipse by user libraries etc. for the following features to work. Especially the resolution of the inheritance hierarchy of a test class (e.g. if your project uses PHPUnit, the hierarchy to PHPUnit_Framework_TestCase) is required.

Runs tests from the active editor.

To run tests, do right click in the editor, and select Run Tests In or Run Tests Related to This File from the context menu.

Run Tests In has the three sub menus Context, Class, File, which are activated if the current editing file is test code, and these have different behaviors.

Run Tests Related to This File runs tests that are related to the classes that are included in the current editing file, and all its subclasses. This command can be run even though the current editing file is production code.

These behaviors are summarized as follows:

In case of editing test code

Command	Tests which will be run
Run Tests In - Context	Tests which are included in the minimal element at the cursor's position (a method or class or file)
Run Tests In - Class	Tests which are included in the class at the cursor's position
Run Tests In - File	Tests which are included in the file
Run Tests Related to This File	Tests which are included in the class(es) and all its subclasses

In case of editing production code

Command	Tests which will be run
Run Tests In - Context	n/a
Run Tests In - Class	n/a
Run Tests In - File	n/a
Run Tests Related to This File	Tests that are related to the classes and all its subclasses

Debugs a test.¶

There are two operation modes for MakeGood, Run Mode and Debug Mode. When the current operation mode is Run Mode, a test is simply run. When Debug Mode, a test is run in the debugger.

To debug a test, click the Debug Test button on the MakeGood view so that the button is pushed in. While The button is being pushed, tests are run in the debugger.

Reruns the last test.¶

Reruns the previously running test.

NOTE: A test which was run by Runs all tests when a file is saved. is not a target.

To rerun the last test, click the Rerun Test button on the MakeGood view.

Stops the test run.¶

Stops the test run in progress.

To stop the test run, click the Stop Test button on the MakeGood view.

Stops on the first failure or error.¶

Stops the test run when the first failure or error is raised.

To enable this feature, click the Stop on Failure/Error button on the MakeGood view so that the button is pushed in.

Analyzing Test Results¶

Tracks failures and errors.¶

The failures and errors of the last test have been set to files as markers.

To track failures and errors, click the Next Failure/Error button or the Previous Failure/Error button. The following actions are executed when a button is clicked.

• Opens the PHP file with the line number where the assertion is defined if the element is failure.
• Opens the PHP file with the line number where the error is raised if the element is error.
• Moves the focus of the result tree on the MakeGood view to the target line.
• Displays the stack trace on the MakeGood view.

The message is popped up when the mouse cursor is over a marker.

The Next Failure/Error button and Previous Failure/Error button are displayed in cyclic order as follows:

• If the current selected failure is the last one, the first failure is displayed when clicking the Previous Failure/Error button.
• If the current selected failure is the first one, the last failure is displayed when clicking the Next Failure/Error button.

Tracks a fatal error.¶

The PHP file with the line number is opened where the error is raised if a fatal error is raised when running a test.

If the file is included in the project, the error is set to the file as a marker. The error message is popped up when the mouse cursor is over the marker.

If the error message cannot be parsed, the message is output into the Error Log view and the Console view is displayed.

Displays the last test result in the status bar.¶

The last test result is displayed in the status bar. The rules are the following:

• Displays the green icon when all tests were passed.
• Displays the red icon when one or more tests were failed.
• Displays the gray icon when the test run was stopped on the way.

The MakeGood view is opened when clicking the icon.

Configuration¶

Selecting the default value for the feature "Run tests when file is saved"¶

This parameter is used to determine the default behavior of the feature Runs tests when a file is saved. (Autotest). The default is All Tests.

The following describes relationship between each button and its behavior:

Button	Behavior
All Tests	Runs all tests when file is saved.
Last Test	Runs the last test when file is saved.
None	Do nothing when file is saved.

To select the default value, configure the preferences for the workspace as the following:

1. Open the preferences.
2. Select MakeGood.
3. Specify one of All Tests, Last Test, and None.

Using the System Include Path¶

In PDT PHP executables, the include path which is defined by the PHP ini file is destroyed, and the include path for the project is activated instead.

In MakeGood, the include path can be used explicitly which is defined by the PHP ini file. The configuration process is as the following:

1. Open the properties for the project.
2. Select PHP Include Path.
3. Click the Add the System Include Path button.

Using a Preload Script¶

A script can be specified which makes preparations for a test run, which are the include path, autoloading, and error handling, etc. It is evaluated before the test runner body is loaded.

See a real-world example. The following is a preload script of Stagehand_TestRunner a product of Piece Framework which is used as the backend of MakeGood.

tests/prepare.php:

<?php
if (defined('E_DEPRECATED')) {
    error_reporting(E_ALL & ~E_DEPRECATED);
} else {
    error_reporting(E_ALL);
}

set_include_path(realpath(dirname(__FILE__) . '/../examples') . PATH_SEPARATOR .
                 realpath(dirname(__FILE__) . '/../src') . PATH_SEPARATOR .
                 get_include_path()
                 );

require_once 'PHPUnit/Framework.php';
require_once 'Stagehand/Autoload.php';

$loader = Stagehand_Autoload::legacyLoader();
$loader->addNamespace('Stagehand');
Stagehand_Autoload::register($loader);

Stagehand_LegacyError_PHPError::enableConversion();

To use a preload script, configure the properties for the project as the following:

1. Open the properties for the project.
2. Select MakeGood.
3. Specify the Preload Script.

If you do not use a preload script, empty the textbox.

Selecting a Testing Framework¶

MakeGood supports PHPUnit, CIUnit, SimpleTest, and CakePHP. you can select which frameworks to use in the project. The default is PHPUnit.

To select a testing framework, configure the properties for the project as the following:

1. Open the properties for the project.
2. Select MakeGood.
3. Specify the Testing Framework

Resolving the Dependencies to the Testing Framework¶

NOTE: If your project cannot solve the dependencies to its testing framework, the message PHPUnit_Framework_TestCase class is not available. Fix... is displayed in the MakeGood view. (In the case of PHPUnit)

To run tests with MakeGood, you must resolve the dependencies to the testing framework for your project. The main solutions are as follows:

• (Recommended) Add user libraries including the testing framework and its dependent packages to the project's property PHP Include Path.
• Place the testing framework and its dependent packages into your project.

The configuration process of the former is as follows:

Defining User Libraries¶

Select Window -> Preferences... from the menu bar, and select PHP -> PHP Libraries. Next, click the New... button, and input the library name and click the OK button.

Next, select the previously defined user library, and click the Add External folder... button. And select the folder where the testing framework is located from the folder selection dialog.

Adding User Libraries to the Project¶

Open the properties for the project, and select the Libraries tab on PHP Include Path, and click the Add Library... button. Next, select User Library and click the Next > button.

Next, check the previously defined user library and click the Finish button.

If no problem, the message Waiting for a test run... is displayed in the MakeGood view.

Specifying the Test Folders¶

Specify the folders to be tested by Run all tests.

To specify the test folders, configure the properties for the project as the following:

1. Open the properties for the project.
2. Select MakeGood.
3. Edit Test Folders using the Add Folder or Remove button.

Key Bindings¶

To run commands from keyboard, shortcut keys can be assigned to the MakeGood commands.

First, select Window -> Preferences... from the menu bar, and select General -> Keys. Next, type makegood into the textbox where type filter text is displayed. Next, configure key bindings.

The Default Key Bindings¶

The default key bindings for MakeGood comamnds are as follows:

Command	Binding	When
Run All Tests	Alt+M A	In Windows
Rerun Test	Alt+M R	In Windows
Stop Test	Atl+M S	In Windows
Run All Tests when File is Saved	Alt+M U	In Windows
Run Last Test when File is Saved	Alt+M I	In Windows
Debug Test	Alt+M B	In Windows
Stop on Failure/Error	Alt+M E	In Windows
Next Failure/Error	Alt+M J	In Windows
Previous Failure/Error	Alt+M K	In Windows
Show Only Failures/Errors	Alt+M O	In MakeGood View
Run Tests In Context	Alt+M C	Editing PHP source
Run Tests In Class	Alt+M L	Editing PHP source
Run Tests In File	Alt+M F	Editing PHP source
Run Tests Related to This File	Alt+M D	Editing PHP source
Run Tests	Alt+M X	In Windows
Show View (View: MakeGood)		Views

Testing Framework Specific Configuration¶

PHPUnit¶

Configuring the PHPUnit Runtime Environment by the XML Configuration File¶

The PHPUnit runtime environment can be configured by the XML configuration file.

To specify your XML configuration file, configure the properties for the project as the following:

1. Open the properties for the project.
2. Select MakeGood.
3. Select PHPUnit.
4. Specify the XML Configuration File.

For more information about the format of the XML configuration file, see PHPUnit Manual - Appendix C. The XML Configuration File.

NOTE: The <testsuites> element is not supported.

NOTE: Also take a look at the known issue Relative paths in a PHPUnit XML file do not work.

CakePHP¶

Specifying the Path of your App Folder¶

By default, /app is used as the path of your app folder.

To specify the path of your app folder, configure the properties for the project as the following:

1. Open the properties for the project.
2. Select MakeGood.
3. Select CakePHP.
4. Specify the app Folder.

Specifying the Path of your CakePHP Libraries Folder¶

By default, the cake folder under the parent directory of your app folder is used as the path of your CakePHP libraries folder. (/path/to/app/../cake)

To specify the path of your CakePHP libraries folder, configure the properties for the project as the following:

1. Open the properties for the project.
2. Select MakeGood.
3. Select CakePHP.
4. Specify the CakePHP libraries folder.

CIUnit¶

CIUnit tests directory¶

By default, /system/application/tests is used as the path of your CIUnit tests directory.

To specify the path of your CIUnit tests directory, configure the properties for the project as the following:

1. Open the properties for the project.
2. Select MakeGood.
3. Select CIUnit.
4. Specify the CIUnit tests directory.

Configuring the PHPUnit Runtime Environment by the XML Configuration File¶

See Configuring the PHPUnit Runtime Environment by the XML Configuration File.

Notes¶

The Conventions for Test Files¶

Test files must conform to the following conventions:

	PHPUnit	SimpleTest	CakePHP	CIUnit
File Names	Test(?:Case)?\.php$	Test(?:Case)?\.php$	\.test\.php$	^test.+\.php$
Class Names	-	-	-	-
Superclasses	PHPUnit_Framework_TestCase	SimpleTestCase	CakeTestCase or CakeWebTestCase	CIUnit_TestCase or CIUnit_TestCase_Selenium

The Console View and Focusing¶

Whether the Console view gets focused when data is written to standard out and standard error is determined by the following two configuration parameters in the Run/Debug -> Console preference page.

• Show When Program Writes to Standard Out
• Show When Program Writes to Standard Error

The above parameters are temporarily disabled while running a test by MakeGood, and the focus will not to be moved to the Console view except a fatal error occurs.

• Console Preferences

Known Issues¶

A test session is not terminated.¶

This is one of critical defects included in PDT for Eclipse Helios SR2. This defect can fix by replacing some plugins with Patched plugin for eclipse-php-helios-SR2.

For more information, see Issue #282.

A key binding conflicts with "Undefined Command".¶

If the MakeGood's command IDs have been changed from the previous versions of MakeGood, a key binding will conflict with Undefined Command.

To remove Undefined Command, configure the preferences for the workspace as the following:

1. Open the preferences.
2. Select General -> Keys -> Filters....
3. Uncheck all checkboxes.
4. Input undefined command on type filter text.
5. Click Restore Command on the target command.

Additional INI files are not loaded.¶

The Eclipse PDT team decided to introduce the -n option to fix the Bug #324073. So only php.ini from /tmp/zend_debug/... has been loaded, and all additional INI files have not been loaded.

This has been introduced since PDT 2.2.0 M201010110334 (2010/10/11).

For more information, see Issue #242.

Relative paths in a PHPUnit XML file do not work.¶

Do you have used PHPUnit 3.4.x?

As of PHPUnit 3.5.0, all paths in a XML file are automatically converted to paths based on the absolute path of the XML file.

But this behavior has not been provided by PHPUnit 3.4.x. Additionally, the working directory when running a test is set to the directory where the launcher script exists since MakeGood does not change the working directory.

We recommend to use PHPUnit 3.5.x. But if you want to use PHPUnit 3.4.x, your tests can be worked by changing thw working directory explicitly by your preload script.

For more information, see Issue #240.

No output to the Debug Output view when running a test with Xdebug.¶

This is a known behavior of PDT. This problem occurs when the current operation mode is Run Mode.

Can't add nested directories to the include path.¶

At the present time, nested directories cannot be added to the include path in PDT.

If the PEAR directory (php_dir) of your environment is /usr/share/php, Stagehand_TestRunner has been located in the directory /usr/share/php/src. And the dependent packages of Stagehand_TestRunner have been located in the directory /usr/share/php.

The following are solutions to this problem:

• Enable the System Include Path and configure the include_path by PHP ini file.
• Configure the include_path by a Preload Script.
• (not recommend) Move the directories in php_dir/src into php_dir.

NOTE: This problem has been reported to the Eclipse project. Bug 296896 - Allow to use the nested directories as libraries.