<li><a href="/docs/modules/AMQP.md">AMQP.md</a></li><li><a href="/docs/modules/Asserts.md">Asserts.md</a></li><li><a href="/docs/modules/Cli.md">Cli.md</a></li><li><a href="/docs/modules/Db.md">Db.md</a></li><li><a href="/docs/modules/Dbh.md">Dbh.md</a></li><li><a href="/docs/modules/Doctrine1.md">Doctrine1.md</a></li><li><a href="/docs/modules/Doctrine2.md">Doctrine2.md</a></li><li><a href="/docs/modules/Facebook.md">Facebook.md</a></li><li><a href="/docs/modules/Filesystem.md">Filesystem.md</a></li><li><a href="/docs/modules/Kohana.md">Kohana.md</a></li><li><a href="/docs/modules/Laravel4.md">Laravel4.md</a></li><li><a href="/docs/modules/Memcache.md">Memcache.md</a></li><li><a href="/docs/modules/MongoDb.md">MongoDb.md</a></li><li><a href="/docs/modules/Phalcon1.md">Phalcon1.md</a></li><li><a href="/docs/modules/PhpBrowser.md">PhpBrowser.md</a></li><li><a href="/docs/modules/REST.md">REST.md</a></li><li><a href="/docs/modules/Redis.md">Redis.md</a></li><li><a href="/docs/modules/SOAP.md">SOAP.md</a></li><li><a href="/docs/modules/Sequence.md">Sequence.md</a></li><li><a href="/docs/modules/Silex.md">Silex.md</a></li><li><a href="/docs/modules/Symfony1.md">Symfony1.md</a></li><li><a href="/docs/modules/Symfony2.md">Symfony2.md</a></li><li><a href="/docs/modules/WebDriver.md">WebDriver.md</a></li><li><a href="/docs/modules/XMLRPC.md">XMLRPC.md</a></li><li><a href="/docs/modules/Yii1.md">Yii1.md</a></li><li><a href="/docs/modules/Yii2.md">Yii2.md</a></li><li><a href="/docs/modules/ZF1.md">ZF1.md</a></li><li><a href="/docs/modules/ZF2.md">ZF2.md</a></li>

<li><a href="/docs/reference/Autoload.md">Autoload.md</a></li><li><a href="/docs/reference/Commands.md">Commands.md</a></li><li><a href="/docs/reference/Configuration.md">Configuration.md</a></li><li><a href="/docs/reference/Fixtures.md">Fixtures.md</a></li><li><a href="/docs/reference/Locator.md">Locator.md</a></li><li><a href="/docs/reference/Stub.md">Stub.md</a></li><li><a href="/docs/reference/XmlBuilder.md">XmlBuilder.md</a></li>

layout: doc

title: Introduction - Codeception - Documentation

The idea behind testing is not new. You can't sleep well if you are not confident that your last commit didn't take down the whole application.

Having your application covered with tests gives you more trust in the stability of your application. That's all.

In most cases tests don't guarantee that the application works 100% as it is supposed to. You can't predict all possible scenarios and exceptional situations for complex apps.

But you can cover with tests the most important parts of your app and at least be sure they work as predicted.

There are plenty of ways to test your application. The most popular paradigm is [Unit Testing](http://en.wikipedia.org/wiki/Unit_testing). As for web applications, testing the controller, or model in isolation doesn't prove your application is working. To test the behavior of your application as a whole, you should write functional or acceptance tests.

The Codeception testing framework distinguishes these levels of testing. Out of the box you have tools for writing unit, functional, and acceptance tests in a single manner.

Let's review the listed testing paradigms in reverse order.

How does your client, manager, or tester, or any other non-technical person, know your site is working? By opening browser, accessing a site, clicking on links, filling the forms, and actually seeing the contant on a web page. That person has no idea of the framework, database, web-server, or programming language you use or why application did not behave as it was expected.

Acceptance tests can cover standard but complex scenarios from a user's perspective. With acceptance tests you can be confident that users, following all defined scenarios, won't get errors.

Please, note that **any web site** can be covered with acceptance tests. Even if you use a very custom CMS or framework.

{% highlight php %}

$I->amOnPage('/');

$I->click('Sign Up');

$I->submitForm('#signup', array('username' => 'MilesDavis', 'email' => 'miles@davis.com'));

$I->see('Thank you for Signing Up!');

?>

{% endhighlight %}

* can be run on any website

* can test javascript and ajax requests

* can be shown to your clients and managers

* most stable in support: less affected by changes in source code or technologies.

* the slowest: requires running browser and database repopulation.

* fewer checks can lead to false-positive results

* yep, they are really slow.

* not stable in execution: rendering and javascript issues, can lead to unpredicted results.

What if we could check our application without running it on a server? In this way we could see detailed exceptions on errors, have tests running faster, and check database for values we expect. That's a are what functional tests are for.

For functional tests you emulate a web request ($_GET, $_POST variables) and send it into your application which returns HTML response. Inside a test you can make assertions about the response, also you can check the data was succesfully stored into database.

For functional tests your application should be prepared to be run in test environment. Codeception provides connectors to several popular PHP frameworks, but you can write your own.

{% highlight php %}

$I->amOnPage('/');

$I->click('Sign Up');

$I->submitForm('#signup', array('username' => 'MilesDavis', 'email' => 'miles@davis.com'));

$I->see('Thank you for Signing Up!');

$I->seeEmailSent('miles@davis.com', 'Thank you for registration');

$I->seeInDatabase('users', array('email' => 'miles@davis.com'));

?>

{% endhighlight %}

* like acceptance tests, but much faster.

* can provide more detailed reports.

* you can still show this code to managers and clients.

* stable enough: only major code changes, or moving to other framework, can break them.

* javascript and ajax can't be tested.

* by emulating the browser you might get more false-positive results.

* require a framework.

Testing pieces of code before coupling them together is highly important as well. This way you can be sure that some deeply hidden feature still works, even it was not touched by functional or acceptance tests. This also proves you produced stable and testable code.

Codeception is created on top of [PHPUnit](http://www.phpunit.de/). If you have experience writing unit tests with PHPUnit you can continue doing so. Codeception has no problem executing standard PHPUnit tests.

But Codeception provides some good tools to make your unit tests simpler and cleaner. Even inexperienced developers should understand what is tested and how. Requirements and code can change rapidly, and unit tests should be updated every time to fit requirements. The better you understand the testing scenario, the faster you can update it for new behavior.

{% highlight php %}

$user->setName('Miles');

$user->setSurname('Davis');

$user->save();

$this->assertEquals('Miles Davis', $user->getFullName());

$this->unitTester->seeInDatabase('users',array('name' => 'Miles', 'surname' => 'Davis'));

}

?>

{% endhighlight %}

* fastest (well, in the current example, you still need database repopulation).

* can cover rarely used features.

* can test stability of application core.

* you can only be considered a good developer if you write them :)

* doesn't test connections between units.

* unstable in support: very sensitive to code changes.

Despite the wide popularity of TDD, not all PHP developers ever write automatic tests for their applications. The Codeception framework was developed to make the testing actually fun. It allows writing unit, functional, integration, and acceptance tests in one style.

It could be called a BDD framework. All Codeception tests are written in a descriptive manner. Just by looking in the test body you can get a clear understanding of what is being tested and how it is performed. Even complex tests with many assertions are written in a simple PHP DSL.

* **Next Chapter: [GettingStarted.md >](/docs/02-GettingStarted.md)**

layout: doc

title: Getting Started - Codeception - Documentation

Let's take a look into Codeception architecture. We assume that you already [installed](http://codeception.com/install) it, and bootstrapped your first test suites. Codeception has generated three of them: unit, functional, and acceptance. They are well described in the previous chapter. Inside your __/tests__ folder you will have three config files and three directories with names corresponding to these suites. Suites are independent groups of tests with a common purpose.

One of the main concepts of Codeception is representation of tests as actions of a person. We have a UnitTester, who executes functions and tests the code. We also have a FunctionalTester, a qualified tester, who tests the application as a whole, with knowledge of its internals. And a AcceptanceTester, a user who works with our application through an interface that we provide.

Each of these Actors are PHP classes along with the actions that they are allowed to do. As you can see, each of these Actors have different abilities. They are not constant, you can extend them. One Actor belongs to one testing suite.

Actor classes are not written but generated from suite configuration. When you change configuration actor classes are **rebuilt automatically**.

If Actor classes are not created or updated as you expect, try to generate them manually with `build` command:

{% highlight yaml %}

$ php codecept.phar build

{% endhighlight %}

By default tests are written as narrative scenarios. To make a PHP file a valid scenario, its name should have a `Cept` suffix.

Let's say, we created a file `tests/acceptance/SigninCept.php`

We can do that by running command:

{% highlight yaml %}

$ php codecept.phar generate:cept acceptance Signin

{% endhighlight %}

{% highlight php %}

{% endhighlight %}

A Scenario always starts with Actor class initialization. After that, writing a scenario is just like typing `$I->` and choosing a proper action from the auto-completion list.

Let's sign in to our site. We assume that we have a 'login' page where we are getting authenticated by login and password. Then we are moved to a user page, where we see the text `Hello, %username%`. Let's look at how this scenario is written in Codeception.

{% highlight php %}

$I->wantTo('log in as regular user');

$I->amOnPage('/login');

$I->fillField('Username','davert');

$I->fillField('Password','qwerty');

$I->click('Login');

$I->see('Hello, davert');

?>

{% endhighlight %}

Before we execute this test, we should make sure that the site is running on a local web server. Let's open the `tests/acceptance.suite.yml` file and replace the URL with the URL of your web application:

{% highlight yaml %}

yaml

config:

PhpBrowser:

url: 'http://myappurl.local'

{% endhighlight %}

After we configured utl we can run this test with `run` command:

{% highlight yaml %}

bash

$ php codecept.phar run

{% endhighlight %}

Here is the output we should see:

{% highlight yaml %}

bash

Acceptance Tests (1) -------------------------------

Trying log in as regular user (SigninCept.php) Ok

Functional Tests (0) -------------------------------

Unit Tests (0) -------------------------------------

Time: 1 second, Memory: 21.00Mb

OK (1 test, 1 assertions)

{% endhighlight %}

Let's get a detailed output:

{% highlight yaml %}

bash

$ php codecept.phar run acceptance --steps

{% endhighlight %}

We should see a step-by-step report on the performed actions.

{% highlight yaml %}

bash

Acceptance Tests (1) -------------------------------

Trying to log in as regular user (SigninCept.php)

Scenario:

* I am on page "/login"

* I fill field "Username" "davert"

* I fill field "Password" "qwerty"

* I click "Login"

* I see "Hello, davert"

OK

Time: 0 seconds, Memory: 21.00Mb

OK (1 test, 1 assertions)

{% endhighlight %}

That was a very simple test that you can reproduce for your own site.

By emulating the user's actions you can test all of your site the same way.

Give it a try!

The actions in Actor classes are taken from modules. Generated Actor classes emulate multiple inheritance. Modules are designed to have one action performed with one method. According to the [DRY principle](http://en.wikipedia.org/wiki/Don%27t_repeat_yourself), if you use the same scenario components in different modules, you can combine them and move them to a custom module. By default each suite has an empty module, which can be used to extend Actor classes. They are stored in the ___support__ directory.

Each suite has its own bootstrap file. It's located in the suite directory and is named `_bootstrap.php`. It will be executed before test suite. There us also a global bootstrap file located in `tests` directory. It can be used to include additional files.

Codeception supports three test formats. Besides the previously described scenario-based Cept format, Codeception can also execute [PHPUnit test files for unit testing](http://codeception.com/docs/06-UnitTests), and [class-based Cest](http://codeception.com/docs/07-AdvancedUsage#Cest-Classes) format. They are covered in later chapters. There is no difference in the way the tests of either format will be run in the suite.

Codeception has a global configuration in `codeception.yml` and a config for each suite. We also support `.dist` configuration files. If you have several developers in a project, put shared settings into `codeception.dist.yml` and personal settings into `codeception.yml`. Same goes for suite configs. For example, the `unit.suite.yml` will be merged with `unit.suite.dist.yml`.

Tests can be started with the `run` command.

{% highlight yaml %}

bash

$ php codecept.phar run

{% endhighlight %}

With the first argument you can run tests from one suite.

{% highlight yaml %}

bash

$ php codecept.phar run acceptance

{% endhighlight %}

To run exactly one test, add a second argument. Provide a local path to the test, from the suite directory.

{% highlight yaml %}

bash

$ php codecept.phar run acceptance SigninCept.php

{% endhighlight %}

Alternatively you can provide full path to test file:

{% highlight yaml %}

bash

$ php codecept.phar run tests/acceptance/SigninCept.php

{% endhighlight %}

You can provide a directory path as well:

{% highlight yaml %}

bash

$ php codecept.phar run tests/acceptance/backend

{% endhighlight %}

Which will execute all tests from backend dir.

To execute a group of tests that are not stored in the same dir you can organize them in [groups](http://codeception.com/docs/07-AdvancedUsage#Groups).

To generate JUnit XML output you can provide `--xml` option, and `--html` for HTML report.

{% highlight yaml %}

bash

$ php codecept.phar run --steps --xml --html

{% endhighlight %}

This command will run all tests for all suites, displaying the steps, and building HTML and XML reports. Reports will be store in `tests/_output/` directory.

And to learn all available options:

{% highlight yaml %}

bash

$ php codecept.phar help run

{% endhighlight %}

To receive detailed output tests can be executed with `--debug` option.

You may print any information inside a test using `codecept_debug` function.

There are plenty of useful Codeception commands.

* `generate:cept` *suite* *filename* - Generates a sample Cept scenario.

* `generate:cest` *suite* *filename* - Generates a sample Cest test.

* `generate:test` *suite* *filename* - Generates a sample PHPUnit Test with Codeception hooks.

* `generate:phpunit` *suite* *filename* - Generates a classic PHPUnit Test.

* `generate:suite` *suite* *guy* - Generates a new suite with the given Guy class name.

* `generate:scenarios` *suite* - Generates text files containing scenarios from tests.

We took a look into the Codeception structure. Most of the things you need were already generated by the `bootstrap` command. After you have reviewed the basic concepts and configurations, you can start writing your first scenarios.

* **Next Chapter: [ModulesAndHelpers.md >](/docs/03-ModulesAndHelpers.md)**

* **Previous Chapter: [< Introduction.md](/docs/01-Introduction.md)**