configuration.xml

<?xml version="1.0" encoding="utf-8" ?>

<appendix id="appendixes.configuration">
  <title>The XML Configuration File</title>

  <section id="appendixes.configuration.phpunit">
    <title>PHPUnit</title>

    <para>
      The attributes of the <literal><![CDATA[<phpunit>]]></literal> element can
      be used to configure PHPUnit's core functionality.
    </para>

    <screen><![CDATA[<phpunit
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:noNamespaceSchemaLocation="http://schema.phpunit.de/4.5/phpunit.xsd"
         backupGlobals="true"
         backupStaticAttributes="false"
         <!--bootstrap="/path/to/bootstrap.php"-->
         cacheTokens="false"
         colors="false"
         convertErrorsToExceptions="true"
         convertNoticesToExceptions="true"
         convertWarningsToExceptions="true"
         forceCoversAnnotation="false"
         mapTestClassNameToCoveredClassName="false"
         printerClass="PHPUnit_TextUI_ResultPrinter"
         <!--printerFile="/path/to/ResultPrinter.php"-->
         processIsolation="false"
         stopOnError="false"
         stopOnFailure="false"
         stopOnIncomplete="false"
         stopOnSkipped="false"
         testSuiteLoaderClass="PHPUnit_Runner_StandardTestSuiteLoader"
         <!--testSuiteLoaderFile="/path/to/StandardTestSuiteLoader.php"-->
         timeoutForSmallTests="1"
         timeoutForMediumTests="10"
         timeoutForLargeTests="60"
         verbose="false">
  <!-- ... -->
</phpunit>]]></screen>

    <para>
      The XML configuration above corresponds to the default behaviour of the
      TextUI test runner documented in <xref linkend="textui.clioptions" />.
    </para>

    <para>
      Additional options that are not available as command-line options are:
    </para>

    <variablelist>

      <varlistentry>
        <term><literal>convertErrorsToExceptions</literal></term>
        <listitem>
          <para>
            By default, PHPUnit will install an error handler that converts
            the following errors to exceptions:
          </para>

          <itemizedlist>
            <listitem><literal>E_WARNING</literal></listitem>
            <listitem><literal>E_NOTICE</literal></listitem>
            <listitem><literal>E_USER_ERROR</literal></listitem>
            <listitem><literal>E_USER_WARNING</literal></listitem>
            <listitem><literal>E_USER_NOTICE</literal></listitem>
            <listitem><literal>E_STRICT</literal></listitem>
            <listitem><literal>E_RECOVERABLE_ERROR</literal></listitem>
            <listitem><literal>E_DEPRECATED</literal></listitem>
            <listitem><literal>E_USER_DEPRECATED</literal></listitem>
          </itemizedlist>

          <para>
            Set <literal>convertErrorsToExceptions</literal> to
            <literal>false</literal> to disable this feature.
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><literal>convertNoticesToExceptions</literal></term>
        <listitem>
          <para>
            When set to <literal>false</literal>, the error handler installed
            by <literal>convertErrorsToExceptions</literal> will not convert
            <literal>E_NOTICE</literal>, <literal>E_USER_NOTICE</literal>, or
            <literal>E_STRICT</literal> errors to exceptions.
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><literal>convertWarningsToExceptions</literal></term>
        <listitem>
          <para>
            When set to <literal>false</literal>, the error handler installed
            by <literal>convertErrorsToExceptions</literal> will not convert
            <literal>E_WARNING</literal> or <literal>E_USER_WARNING</literal>
            errors to exceptions.
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><literal>forceCoversAnnotation</literal></term>
        <listitem>
          <para>
            Code Coverage will only be recorded for tests that use the
            <literal>@covers</literal> annotation documented in
            <xref linkend="appendixes.annotations.covers" />.
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><literal>timeoutForLargeTests</literal></term>
        <listitem>
          <para>
            If time limits based on test size are enforced then this attribute
            sets the timeout for all tests marked as <literal>@large</literal>.
            If a test does not complete within its configured timeout, it will
            fail.
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><literal>timeoutForMediumTests</literal></term>
        <listitem>
          <para>
            If time limits based on test size are enforced then this attribute
            sets the timeout for all tests marked as <literal>@medium</literal>.
            If a test does not complete within its configured timeout, it will
            fail.
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><literal>timeoutForSmallTests</literal></term>
        <listitem>
          <para>
            If time limits based on test size are enforced then this attribute
            sets the timeout for all tests not marked as
            <literal>@medium</literal> or <literal>@large</literal>. If a test
            does not complete within its configured timeout, it will fail.
          </para>
        </listitem>
      </varlistentry>
    </variablelist>
  </section>

  <section id="appendixes.configuration.testsuites">
    <title>Test Suites</title>

    <para>
      <indexterm><primary>Test Suite</primary></indexterm>

      The <literal><![CDATA[<testsuites>]]></literal> element and its
      one or more <literal><![CDATA[<testsuite>]]></literal> children can be
      used to compose a test suite out of test suites and test cases.
    </para>

    <screen><![CDATA[<testsuites>
  <testsuite name="My Test Suite">
    <directory>/path/to/*Test.php files</directory>
    <file>/path/to/MyTest.php</file>
    <exclude>/path/to/exclude</exclude>
  </testsuite>
</testsuites>]]></screen>

    <para>
      Using the <literal>phpVersion</literal> and
      <literal>phpVersionOperator</literal> attributes, a required PHP version
      can be specified. The example below will only add the
      <filename>/path/to/*Test.php</filename> files and
      <filename>/path/to/MyTest.php</filename> file if the PHP version is at
      least 5.3.0.
    </para>

    <screen><![CDATA[  <testsuites>
    <testsuite name="My Test Suite">
      <directory suffix="Test.php" phpVersion="5.3.0" phpVersionOperator=">=">/path/to/files</directory>
      <file phpVersion="5.3.0" phpVersionOperator=">=">/path/to/MyTest.php</file>
    </testsuite>
  </testsuites>]]></screen>

    <para>
      The <literal>phpVersionOperator</literal> attribute is optional and
      defaults to <literal><![CDATA[>=]]></literal>.
    </para>
  </section>

  <section id="appendixes.configuration.groups">
    <title>Groups</title>

    <para>
      <indexterm><primary>Test Groups</primary></indexterm>

      The <literal><![CDATA[<groups>]]></literal> element and its
      <literal><![CDATA[<include>]]></literal>,
      <literal><![CDATA[<exclude>]]></literal>, and
      <literal><![CDATA[<group>]]></literal> children can be used to select
      groups of tests marked with the <literal>@group</literal> annotation
      (documented in <xref linkend="appendixes.annotations.group" />)
      that should (not) be run.
    </para>

    <screen><![CDATA[<groups>
  <include>
    <group>name</group>
  </include>
  <exclude>
    <group>name</group>
  </exclude>
</groups>]]></screen>

    <para>
      The XML configuration above corresponds to invoking the TextUI test runner
      with the following options:
    </para>

    <itemizedlist>
      <listitem><para><literal>--group name</literal></para></listitem>
      <listitem><para><literal>--exclude-group name</literal></para></listitem>
    </itemizedlist>
  </section>

  <section id="appendixes.configuration.blacklist-whitelist">
    <title>Including and Excluding Files for Code Coverage</title>

    <para>
      <indexterm><primary>Code Coverage</primary></indexterm>
      <indexterm><primary>Blacklist</primary></indexterm>
      <indexterm><primary>Whitelist</primary></indexterm>

      The <literal><![CDATA[<filter>]]></literal> element and its children can
      be used to configure the blacklist and whitelist for the code coverage
      reporting.
    </para>

    <screen><![CDATA[<filter>
  <blacklist>
    <directory suffix=".php">/path/to/files</directory>
    <file>/path/to/file</file>
    <exclude>
      <directory suffix=".php">/path/to/files</directory>
      <file>/path/to/file</file>
    </exclude>
  </blacklist>
  <whitelist processUncoveredFilesFromWhitelist="true">
    <directory suffix=".php">/path/to/files</directory>
    <file>/path/to/file</file>
    <exclude>
      <directory suffix=".php">/path/to/files</directory>
      <file>/path/to/file</file>
    </exclude>
  </whitelist>
</filter>]]></screen>
  </section>

  <section id="appendixes.configuration.logging">
    <title>Logging</title>

    <para>
      <indexterm><primary>Logging</primary></indexterm>

      The <literal><![CDATA[<logging>]]></literal> element and its
      <literal><![CDATA[<log>]]></literal> children can be used to configure the
      logging of the test execution.
    </para>

    <screen><![CDATA[<logging>
  <log type="coverage-html" target="/tmp/report" lowUpperBound="35"
       highLowerBound="70"/>
  <log type="coverage-clover" target="/tmp/coverage.xml"/>
  <log type="coverage-php" target="/tmp/coverage.serialized"/>
  <log type="coverage-text" target="php://stdout" showUncoveredFiles="false"/>
  <log type="json" target="/tmp/logfile.json"/>
  <log type="tap" target="/tmp/logfile.tap"/>
  <log type="junit" target="/tmp/logfile.xml" logIncompleteSkipped="false"/>
  <log type="testdox-html" target="/tmp/testdox.html"/>
  <log type="testdox-text" target="/tmp/testdox.txt"/>
</logging>]]></screen>

    <para>
      The XML configuration above corresponds to invoking the TextUI test runner
      with the following options:
    </para>

    <itemizedlist>
      <listitem><para><literal>--coverage-html /tmp/report</literal></para></listitem>
      <listitem><para><literal>--coverage-clover /tmp/coverage.xml</literal></para></listitem>
      <listitem><para><literal>--coverage-php /tmp/coverage.serialized</literal></para></listitem>
      <listitem><para><literal>--coverage-text</literal></para></listitem>
      <listitem><para><literal>--log-json /tmp/logfile.json</literal></para></listitem>
      <listitem><para><literal><![CDATA[>]]> /tmp/logfile.txt</literal></para></listitem>
      <listitem><para><literal>--log-tap /tmp/logfile.tap</literal></para></listitem>
      <listitem><para><literal>--log-junit /tmp/logfile.xml</literal></para></listitem>
      <listitem><para><literal>--testdox-html /tmp/testdox.html</literal></para></listitem>
      <listitem><para><literal>--testdox-text /tmp/testdox.txt</literal></para></listitem>
    </itemizedlist>

    <para>
      The <literal>lowUpperBound</literal>, <literal>highLowerBound</literal>,
      <literal>logIncompleteSkipped</literal> and
      <literal>showUncoveredFiles</literal> attributes have no equivalent TextUI
      test runner option.
    </para>

    <itemizedlist>
      <listitem><para><literal>lowUpperBound</literal>: Maximum coverage percentage to be considered "lowly" covered.</para></listitem>
      <listitem><para><literal>highLowerBound</literal>: Minimum coverage percentage to be considered "highly" covered.</para></listitem>
      <listitem><para><literal>showUncoveredFiles</literal>: Show all whitelisted files in <literal>--coverage-text</literal> output not just the ones with coverage information.</para></listitem>
      <listitem><para><literal>showOnlySummary</literal>: Show only the summary in <literal>--coverage-text</literal> output.</para></listitem>
    </itemizedlist>
  </section>

  <section id="appendixes.configuration.test-listeners">
    <title>Test Listeners</title>

    <para>
      <indexterm><primary>PHPUnit_Framework_TestListener</primary></indexterm>
      <indexterm><primary>Test Listener</primary></indexterm>

      The <literal><![CDATA[<listeners>]]></literal> element and its
      <literal><![CDATA[<listener>]]></literal> children can be used to attach
      additional test listeners to the test execution.
    </para>

    <screen><![CDATA[<listeners>
  <listener class="MyListener" file="/optional/path/to/MyListener.php">
    <arguments>
      <array>
        <element key="0">
          <string>Sebastian</string>
        </element>
      </array>
      <integer>22</integer>
      <string>April</string>
      <double>19.78</double>
      <null/>
      <object class="stdClass"/>
    </arguments>
  </listener>
</listeners>]]></screen>

    <para>
      The XML configuration above corresponds to attaching the
      <literal>$listener</literal> object (see below) to the test execution:
    </para>

    <screen><![CDATA[$listener = new MyListener(
  array('Sebastian'),
  22,
  'April',
  19.78,
  NULL,
  new stdClass
);]]></screen>
  </section>

  <section id="appendixes.configuration.php-ini-constants-variables">
    <title>Setting PHP INI settings, Constants and Global Variables</title>

    <para>
      <indexterm><primary>Constant</primary></indexterm>
      <indexterm><primary>Global Variable</primary></indexterm>
      <indexterm><primary><literal>php.ini</literal></primary></indexterm>

      The <literal><![CDATA[<php>]]></literal> element and its children can be
      used to configure PHP settings, constants, and global variables. It can
      also be used to prepend the <literal>include_path</literal>.
    </para>

    <screen><![CDATA[<php>
  <includePath>.</includePath>
  <ini name="foo" value="bar"/>
  <const name="foo" value="bar"/>
  <var name="foo" value="bar"/>
  <env name="foo" value="bar"/>
  <post name="foo" value="bar"/>
  <get name="foo" value="bar"/>
  <cookie name="foo" value="bar"/>
  <server name="foo" value="bar"/>
  <files name="foo" value="bar"/>
  <request name="foo" value="bar"/>
</php>]]></screen>

    <para>
      The XML configuration above corresponds to the following PHP code:
    </para>

    <screen><![CDATA[ini_set('foo', 'bar');
define('foo', 'bar');
$GLOBALS['foo'] = 'bar';
$_ENV['foo'] = 'bar';
$_POST['foo'] = 'bar';
$_GET['foo'] = 'bar';
$_COOKIE['foo'] = 'bar';
$_SERVER['foo'] = 'bar';
$_FILES['foo'] = 'bar';
$_REQUEST['foo'] = 'bar';]]></screen>
  </section>

  <section id="appendixes.configuration.selenium-rc">
    <title>Configuring Browsers for Selenium RC</title>

    <para>
      <indexterm><primary>Selenium RC</primary></indexterm>

      The <literal><![CDATA[<selenium>]]></literal> element and its
      <literal><![CDATA[<browser>]]></literal> children can be used to
      configure a list of Selenium RC servers.
    </para>

    <screen><![CDATA[<selenium>
  <browser name="Firefox on Linux"
           browser="*firefox /usr/lib/firefox/firefox-bin"
           host="my.linux.box"
           port="4444"
           timeout="30000"/>
</selenium>]]></screen>

    <para>
      The XML configuration above corresponds to the following PHP code:
    </para>

    <screen><![CDATA[class WebTest extends PHPUnit_Extensions_SeleniumTestCase
{
    public static $browsers = array(
      array(
        'name'    => 'Firefox on Linux',
        'browser' => '*firefox /usr/lib/firefox/firefox-bin',
        'host'    => 'my.linux.box',
        'port'    => 4444,
        'timeout' => 30000
      )
    );

    // ...
}]]></screen>
  </section>
</appendix>