text: <?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="https://schema.phpunit.de/7.0/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"
           stopOnRisky="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.whitelisting-files">
      <title>Whitelisting Files for Code Coverage</title>
  
      <para>
        <indexterm><primary>Code Coverage</primary></indexterm>
        <indexterm><primary>Whitelist</primary></indexterm>
  
        The <literal><![CDATA[<filter>]]></literal> element and its children can
        be used to configure the whitelist for the code coverage reporting.
      </para>
  
      <screen><![CDATA[<filter>
    <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="junit" target="/tmp/logfile.xml"/>
    <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><![CDATA[>]]> /tmp/logfile.txt</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>,
        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(
      ['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>
  </appendix>
  