repo_zf1/documentation/manual/en/module_specs/Zend_Test-PHPUnit-Assertions.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->
<sect2 id="zend.test.phpunit.assertions">
    <title>Assertions</title>

    <para>
        Assertions are at the heart of Unit Testing; you use them to verify
        that the results are what you expect. To this end,
        <classname>Zend_Test_PHPUnit_ControllerTestCase</classname> provides a number of
        assertions to make testing your <acronym>MVC</acronym> apps and controllers simpler.
    </para>

    <sect3 id="zend.test.phpunit.assertions.query">
        <title>CSS Selector Assertions</title>

        <para>
            <acronym>CSS</acronym> selectors are an easy way to verify that certain artifacts are
            present in the response content. They also make it trivial to
            ensure that items necessary for Javascript UIs and/or <acronym>AJAX</acronym>
            integration will be present; most JS toolkits provide some
            mechanism for pulling DOM elements based on <acronym>CSS</acronym> selectors, so the
            syntax would be the same.
        </para>

        <para>
            This functionality is provided via <link
                linkend="zend.dom.query">Zend_Dom_Query</link>, and integrated
            into a set of 'Query' assertions. Each of these assertions takes
            as their first argument a <acronym>CSS</acronym> selector, with optionally additional
            arguments and/or an error message, based on the assertion type. You
            can find the rules for writing the <acronym>CSS</acronym> selectors in the <link
                linkend="zend.dom.query.operation">Zend_Dom_Query theory of
                operation chapter</link>. Query assertions include:
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    <methodname>assertQuery($path, $message)</methodname>: assert that
                    one or more DOM elements matching the given <acronym>CSS</acronym> selector are
                    present. If a <varname>$message</varname> is present, it will be
                    prepended to any failed assertion message.
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>assertQueryContentContains($path, $match, $message)</methodname>:
                    assert that one or more DOM elements matching the given <acronym>CSS</acronym>
                    selector are present, and that at least one contains the content provided in
                    <varname>$match</varname>. If a <varname>$message</varname> is present, it will
                    be prepended to any failed assertion message.
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>assertQueryContentRegex($path, $pattern, $message)</methodname>:
                    assert that one or more DOM elements matching the given <acronym>CSS</acronym>
                    selector are present, and that at least one matches the regular expression
                    provided in <varname>$pattern</varname>. If a <varname>$message</varname> is
                    present, it will be prepended to any failed assertion message.
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>assertQueryCount($path, $count, $message)</methodname>: assert that
                    there are exactly <varname>$count</varname> DOM elements matching the given
                    <acronym>CSS</acronym> selector present. If a <varname>$message</varname> is
                    present, it will be prepended to any failed assertion message.
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>assertQueryCountMin($path, $count, $message)</methodname>: assert
                    that there are at least <varname>$count</varname> DOM elements matching the
                    given <acronym>CSS</acronym> selector present. If a <varname>$message</varname>
                    is present, it will be prepended to any failed assertion message.
                    <emphasis>Note:</emphasis> specifying a value of 1 for
                    <varname>$count</varname> is the same as simply using
                    <methodname>assertQuery()</methodname>.
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>assertQueryCountMax($path, $count, $message)</methodname>: assert
                    that there are no more than <varname>$count</varname> DOM elements matching the
                    given <acronym>CSS</acronym> selector present. If a <varname>$message</varname>
                    is present, it will be prepended to any failed assertion message.
                    <emphasis>Note:</emphasis> specifying a value of 1 for
                    <varname>$count</varname> is the same as simply using
                    <methodname>assertQuery()</methodname>.
                </para>
            </listitem>
        </itemizedlist>

        <para>
            Additionally, each of the above has a 'Not' variant that provides a
            negative assertion: <methodname>assertNotQuery()</methodname>,
            <methodname>assertNotQueryContentContains()</methodname>,
            <methodname>assertNotQueryContentRegex()</methodname>, and
            <methodname>assertNotQueryCount()</methodname>. (Note that the min and
            max counts do not have these variants, for what should be obvious
            reasons.)
        </para>
    </sect3>

    <sect3 id="zend.test.phpunit.assertions.xpath">
        <title>XPath Assertions</title>

        <para>
            Some developers are more familiar with XPath than with <acronym>CSS</acronym>
            selectors, and thus XPath variants of all the <link
                linkend="zend.test.phpunit.assertions.query">Query
                assertions</link> are also provided. These are:
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    <methodname>assertXpath($path, $message = '')</methodname>
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>assertNotXpath($path, $message = '')</methodname>
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>assertXpathContentContains($path, $match, $message =
                        '')</methodname>
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>assertNotXpathContentContains($path, $match, $message =
                        '')</methodname>
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>assertXpathContentRegex($path, $pattern, $message = '')</methodname>
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>assertNotXpathContentRegex($path, $pattern, $message =
                        '')</methodname>
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>assertXpathCount($path, $count, $message = '')</methodname>
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>assertNotXpathCount($path, $count, $message = '')</methodname>
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>assertXpathCountMin($path, $count, $message = '')</methodname>
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>assertNotXpathCountMax($path, $count, $message = '')</methodname>
                </para>
            </listitem>
        </itemizedlist>
    </sect3>

    <sect3 id="zend.test.phpunit.assertions.redirect">
        <title>Redirect Assertions</title>

        <para>
            Often an action will redirect. Instead of following the redirect,
            <classname>Zend_Test_PHPUnit_ControllerTestCase</classname> allows you to
            test for redirects with a handful of assertions.
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    <methodname>assertRedirect($message = '')</methodname>: assert simply that
                    a redirect has occurred.
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>assertNotRedirect($message = '')</methodname>: assert that no
                    redirect has occurred.
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>assertRedirectTo($url, $message = '')</methodname>: assert that
                    a redirect has occurred, and that the value of the Location
                    header is the <varname>$url</varname> provided.
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>assertNotRedirectTo($url, $message = '')</methodname>: assert that
                    a redirect has either NOT occurred, or that the value of the Location
                    header is NOT the <varname>$url</varname> provided.
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>assertRedirectRegex($pattern, $message = '')</methodname>:
                    assert that a redirect has occurred, and that the value of the
                    Location header matches the regular expression provided by
                    <varname>$pattern</varname>.
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>assertNotRedirectRegex($pattern, $message = '')</methodname>:
                    assert that a redirect has either NOT occurred, or that the value of the
                    Location header does NOT match the regular expression provided by
                    <varname>$pattern</varname>.
                </para>
            </listitem>
        </itemizedlist>
    </sect3>

    <sect3 id="zend.test.phpunit.assertions.header">
        <title>Response Header Assertions</title>

        <para>
            In addition to checking for redirect headers, you will often need
            to check for specific <acronym>HTTP</acronym> response codes and headers -- for
            instance, to determine whether an action results in a 404 or 500
            response, or to ensure that <acronym>JSON</acronym> responses contain the appropriate
            Content-Type header. The following assertions are available.
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    <methodname>assertResponseCode($code, $message = '')</methodname>: assert
                    that the response resulted in the given <acronym>HTTP</acronym> response code.
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>assertHeader($header, $message = '')</methodname>: assert
                    that the response contains the given header.
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>assertHeaderContains($header, $match, $message)</methodname>: assert
                    that the response contains the given header and that its content contains the
                    given string.
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>assertHeaderRegex($header, $pattern, $message)</methodname>: assert
                    that the response contains the given header and that its content matches the
                    given regex.
                </para>
            </listitem>
        </itemizedlist>

        <para>
            Additionally, each of the above assertions have a 'Not' variant for
            negative assertions.
        </para>
    </sect3>

    <sect3 id="zend.test.phpunit.assertions.request">
        <title>Request Assertions</title>

        <para>
            It's often useful to assert against the last run action,
            controller, and module; additionally, you may want to assert
            against the route that was matched. The following assertions can
            help you in this regard:
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    <methodname>assertModule($module, $message = '')</methodname>: Assert that
                    the given module was used in the last dispatched action.
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>assertController($controller, $message = '')</methodname>:
                    Assert that the given controller was selected in the last
                    dispatched action.
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>assertAction($action, $message = '')</methodname>: Assert that
                    the given action was last dispatched.
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>assertRoute($route, $message = '')</methodname>: Assert that
                    the given named route was matched by the router.
                </para>
            </listitem>
        </itemizedlist>

        <para>
            Each also has a 'Not' variant for negative assertions.
        </para>
    </sect3>
</sect2>
<!--
vim:se ts=4 sw=4 et:
-->