Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

Added Unit Testing documentation page #340

Merged
merged 4 commits into from about 2 years ago

2 participants

Chad Miller Harro Verton
Chad Miller

Please see prior discussion at fuel/oil#114. Attn: @WanWizard

Please note that this documentation includes references to the change made in the above-mentioned pull request.

Harro Verton WanWizard merged commit 1f2dcf3 into from
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
This page is out of date. Refresh to see the latest.

Showing 2 changed files with 205 additions and 0 deletions. Show diff stats Hide diff stats

  1. +1 0  assets/js/combined.js
  2. +204 0 general/unit_testing.html
1  assets/js/combined.js
@@ -377,6 +377,7 @@ panes.main = {
377 377 "Packages": "general/packages.html",
378 378 "Security": "general/security.html",
379 379 "Tasks": "general/tasks.html",
  380 + "Unit Testing": "general/unit_testing.html",
380 381 "Error handling": "general/error.html",
381 382 "Profiling": "general/profiling.html",
382 383 }
204 general/unit_testing.html
... ... @@ -0,0 +1,204 @@
  1 +<!doctype html>
  2 +<html lang="en">
  3 +<head>
  4 + <meta charset="UTF-8">
  5 + <meta name="viewport" content="width=device-width, initial-scale=1.0">
  6 + <link rel="stylesheet" href="./../assets/css/combined.css">
  7 + <link rel="shortcut icon" href="./../favicon.ico" />
  8 + <script src="http://www.google.com/jsapi" type="text/javascript"></script>
  9 + <script type="text/javascript">
  10 + var path = './../';
  11 + </script>
  12 + <script src="./../assets/js/combined.js"></script>
  13 + <title>Unit Testing - General - FuelPHP Documentation</title>
  14 +</head>
  15 +<body>
  16 + <div id="container">
  17 + <header id="header">
  18 + <div class="table">
  19 + <h1>
  20 + <strong>FuelPHP, a PHP 5.3 Framework</strong>
  21 + Documentation
  22 + </h1>
  23 +
  24 + <form id="google_search">
  25 + <p>
  26 + <span id="search_clear">&nbsp;</span>
  27 + <input type="submit" name="search_submit" id="search_submit" value="search" />
  28 + <input type="text" value="" id="search_input" name="search_input" />
  29 + </p>
  30 + </form>
  31 + </div>
  32 + <nav>
  33 +
  34 + <div class="clear"></div>
  35 + </nav>
  36 + <a href="#" id="toc_handle">table of contents</a>
  37 + <div class="clear"></div>
  38 + </header>
  39 +
  40 + <div id="cse">
  41 + <div id="cse_point"></div>
  42 + <div id="cse_content"></div>
  43 + </div>
  44 +
  45 + <div id="main">
  46 +
  47 + <h2 id="unit_testing">
  48 + <a class="internal_link" href="#unit_testing">Unit Testing</a>
  49 + </h2>
  50 +
  51 + <p>
  52 + FuelPHP is built with automated unit testing in mind, and it includes tests and test classes based on the <a title="The PHPUnit Testing Framework" href="http://www.phpunit.de/manual/current/en/index.html">PHPUnit</a> testing framework.
  53 + </p>
  54 +
  55 + <h3 id="what_is_a_unit_test">
  56 + <a class="internal_link" href="#what_is_a_unit_test">What is a Unit Test?</a>
  57 + </h3>
  58 +
  59 + <p>
  60 + Unit Tests are automated tests written to make sure a unit of code (typically a function or method) is doing what it was designed to do.
  61 + These tests also help developers to be sure any changes they make to a system do not break anything that is already working.
  62 + Unit tests are also the key driving force behind the discipline of Test Driven Development (TDD).
  63 + </p>
  64 +
  65 + <h3 id="prerequisite">
  66 + <a class="internal_link" href="#prerequisite">PHPUnit</a>
  67 + </h3>
  68 +
  69 + <p>
  70 + You'll need to have <a title="The PHPUnit Testing Framework" href="http://www.phpunit.de/manual/current/en/index.html">PHPUnit</a> installed locally if you want to run the tests that ship with FuelPHP, and if you want to use Oil to run your tests.
  71 + If you don't already have PHPUnit installed, please refer to the PHPUnit installation documentation at: <a title="PHPUnit Installation" href="http://www.phpunit.de/manual/current/en/installation.html">http://www.phpunit.de/manual/current/en/installation.html</a>.
  72 + </p>
  73 +
  74 + <p>
  75 + If you aren't interested in running unit tests with FuelPHP, then there is no need for you to install PHPUnit.
  76 + </p>
  77 +
  78 + <h3 id="running_unit_tests">
  79 + <a class="internal_link" href="#running_unit_tests">Running Unit Tests</a>
  80 + </h3>
  81 +
  82 + <p>
  83 + FuelPHP's included command-line utility Oil is already configured to run your unit tests.
  84 + You can run all the tests in your FuelPHP project from the command line using the Oil command line utility:
  85 + </p>
  86 +
  87 + <pre class="cli"><code>$ php oil test
  88 +
  89 +Tests Running...This may take a few moments.
  90 +PHPUnit 3.6.10 by Sebastian Bergmann.
  91 +
  92 +Configuration read from /home/user/sites/example/fuel/core/phpunit.xml
  93 +
  94 +............................................................... 63 / 251 ( 25%)
  95 +............................................................... 126 / 251 ( 50%)
  96 +............................................................... 189 / 251 ( 75%)
  97 +..............................................................
  98 +
  99 +Time: 6 seconds, Memory: 22.25Mb
  100 +
  101 +OK (251 tests, 206 assertions)</code></pre>
  102 +
  103 + <h3 id="creating_unit_tests">
  104 + <a class="internal_link" href="#creating_unit_tests">Creating Unit Tests</a>
  105 + </h3>
  106 +
  107 + <p>
  108 + In FuelPHP, tests are located in the fuel/app/tests directory and its subdirectories.
  109 + If this directory does not exist, go ahead and create it.
  110 + By convention, test files are placed in the same subpath of fuel/app/tests as the tested class is of fuel/app/classes, so a test for the class at fuel/app/classes/model/login.php would be in the file fuel/app/tests/model/login.php.
  111 + </p>
  112 +
  113 + <p>
  114 + Tests are classes that extend the TestCase class.
  115 + TestCase is FuelPHP's extension of PHPUnit's PHPUnit_Framework_TestCase class, so you'll be able to use all the usual PHPUnit assertions and methods in your test.
  116 + By convention, test classes are named after the class they test, prefixed with Test_, so a test for the Model_Login class would be named Test_Model_Login.
  117 + </p>
  118 +
  119 + <pre class="php"><code>class Test_Model_Login extends TestCase
  120 +{
  121 + public function test_foo()
  122 + {
  123 + }
  124 +}</code></pre>
  125 +
  126 + <p>
  127 + You can find further information about writing tests in the PHPUnit documentation at: <a href="http://www.phpunit.de/manual/current/en/writing-tests-for-phpunit.html">http://www.phpunit.de/manual/current/en/writing-tests-for-phpunit.html</a>.
  128 + </p>
  129 +
  130 + <h3 id="test_groups">
  131 + <a class="internal_link" href="#test_groups">Test Groups</a>
  132 + </h3>
  133 +
  134 + <p>
  135 + If you want to run only a subset of tests during development, you can use test groups.
  136 + Run <code>php oil test</code> with the <code>--group=</code> command switch.
  137 + </p>
  138 +
  139 + <pre class="cli"><code>$ php oil test --group=App</code></pre>
  140 +
  141 + <p>
  142 + This command will run only the tests in the group 'App'.
  143 + You can assign a test class to one or more test groups with the docblock attribute @group.
  144 + </p>
  145 +
  146 + <pre class="php"><code>/**
  147 + * @group App
  148 + * @group Login
  149 + */
  150 +class Test_Model_Login extends TestCase
  151 +{
  152 + public function test_foo()
  153 + {
  154 + }
  155 +}</code></pre>
  156 +
  157 + <h2 id="advanced_configuration">
  158 + <a class="internal_link" href="#advanced_configuration">Advanced Configuration</a>
  159 + </h2>
  160 +
  161 + <p>
  162 + If you need to customize the contents of the phpunit.xml file, copy fuel/core/phpunit.xml into the fuel/app directory.
  163 + FuelPHP will recognize your new configuration file in place of the old one in fuel/core.
  164 + </p>
  165 +
  166 +
  167 + <h3 id="unit_tests_for_modules">
  168 + <a class="internal_link" href="#unit_tests_for_modules">Unit Tests for Modules</a>
  169 + </h3>
  170 +
  171 + <p>
  172 + If you're developing a large system in FuelPHP, the recommended practice is to develop in modules.
  173 + But since module paths are configurable, the module paths must be configured in phpunit.xml in order for the tests to be recognized and run.
  174 + For example, if you are developing modules in fuel/app/modules, you'll want to add this test suite to your phpunit configuration:
  175 + </p>
  176 +
  177 + <pre class="xml"><code>&lt;testsuite name="modules"&gt;
  178 + &lt;directory suffix=".php"&gt;../app/modules/*/tests&lt;/directory&gt;
  179 +&lt;/testsuite&gt;</code></pre>
  180 +
  181 +
  182 + <h3 id="testing_in_a_renamed_directory">
  183 + <a class="internal_link" href="#testing_in_a_renamed_directory">Tesing In A Renamed fuel/ Directory</a>
  184 + </h3>
  185 +
  186 + <p>
  187 + If you've renamed your fuel directory to something else, the system variables (document root, core path, etc.) set in the phpunit.xml file have become bad references.
  188 + While changes to the paths in the Oil script in your root will help with the other Oil commands, PHPUnit loads its own environment, so a renamed fuel directory will break testing.
  189 + To fix this, edit the copy of phpunit.xml in your app/ directory and update the server variable paths to reflect your new file structure.
  190 + </p>
  191 +
  192 +
  193 +
  194 +
  195 + </div>
  196 +
  197 + <footer>
  198 + <p>
  199 + &copy; FuelPHP Development Team 2010-2012 - <a href="http://fuelphp.com">FuelPHP</a> is released under the MIT license.
  200 + </p>
  201 + </footer>
  202 + </div>
  203 +</body>
  204 +</html>

Tip: You can add notes to lines in a file. Hover to the left of a line to make a note

Something went wrong with that request. Please try again.