.. ==================================================
.. FOR YOUR INFORMATION
.. --------------------------------------------------
.. -*- coding: utf-8 -*- with BOM.

.. include:: ../Includes.txt

Unit tests
==========

The ExtensionBuilder creates a basic set of unit tests for the generated code of your extension. This chapter gives
you an overview about the generated tests and explains it's opportunities and limits.

If you're new to unit tests we encourage you to spend some time to learn the benefits of software testing.
It will certainly improve the quality of your software, but will also help to improve your programming skills.

What parts are covered by the generated tests?
----------------------------------------------

The ExtensionBuilder generates default unit tests for the public API of

1. domain models
2. default controller actions

Covered domain model methods
````````````````````````````

* get*()
* set*()
* add*()
* remove*()

For example:

.. code-block:: php

   /**
    * @test
    */
   public function setNameForStringSetsName() {
       $this->subject->setName('Conceived at T3CON10');

       self::assertAttributeEquals(
           'Conceived at T3CON10',
           'name',
           $this->subject
       );
   }


All types of properties are covered, for example integers, strings, file references or relations to other domain models.

Covered ControllerActions
`````````````````````````

* listAction()
* showAction()
* newAction()
* createAction()
* editAction()
* updateAction()
* deleteAction()

The ControllerAction tests cover the following behavior expectations:

* asserting data is assigned to a view
* asserting the action delegates data modifications to a repository, like adding, updating, removing or fetching objects

For example:

.. code-block:: php

   /**
    * @test
    */
   public function deleteActionRemovesTheGivenBlogFromBlogRepository() {
       $blog = new \Vendor\Example\Domain\Model\Blog();

       $blogRepository = $this->getMock(
           'Vendor\\Example\\Domain\\Repository\\BlogRepository',
           ['remove'],
           [],
           '',
           false
       );
       $blogRepository->expects(self::once())->method('remove')->with($blog);
       $this->inject($this->subject, 'blogRepository', $blogRepository);

       $this->subject->deleteAction($blog);
   }

Running your unit tests
-----------------------

Unit tests of your extension can be run in the backend with the TYPO3 Extension `phpunit <http://typo3.org/extensions/repository/view/phpunit>`_

The `Unit Testing page <http://wiki.typo3.org/Unit_Testing_TYPO3>`_ in the TYPO3 wiki provides some hints for those
who like to run their tests natively with phpunit from the command-line.


Opportunities and limitations of autogenerated unit tests
---------------------------------------------------------

The purpose of autogenerated tests is not to hand over the test responsibility to a tool. We rather want to encourage
you to start writing your own tests as soon as you start customizing your code. However, having some basic tests makes it
easier to add new ones.

Learning test tools like phpunit or the backend module of ``EXT:phpunit`` is easier, if you have some test at hand and can
start right away.

It also allows you to refactor with less fear of breaking things. Code which is covered by tests is less likely for
unexpected behaviour after refactoring. Of course this depends on the test cases and the complexity of the code.
However the logic of the generated code is simple and so are the tests. They are meant as a starting point.
Don't expect too much magic. It's all bound to the limits of modeling tools like the extension builder: As soon as your
code pulls off the road, your unit tests will also.

Nevertheless, you can enjoy the green bar feeling for any generated extension.