Skip to content
Permalink
Browse files

updated docs, removed mentions of Cept format

  • Loading branch information
DavertMik committed Mar 31, 2018
1 parent 853683f commit 543839658a2ffd360ec10efc873f5d615b313116
@@ -48,7 +48,6 @@ With acceptance tests, you can be confident that users, following all the define

```php
<?php
$I = new AcceptanceTester($scenario);
$I->amOnPage('/');
$I->click('Sign Up');
$I->submitForm('#signup', ['username' => 'MilesDavis', 'email' => 'miles@davis.com']);
@@ -72,7 +71,6 @@ Codeception provides connectors to several popular PHP frameworks. You can also

```php
<?php
$I = new FunctionalTester($scenario);
$I->amOnPage('/');
$I->click('Sign Up');
$I->submitForm('#signup', ['username' => 'MilesDavis', 'email' => 'miles@davis.com']);
@@ -106,7 +104,7 @@ function testSavingUser()
$user->setSurname('Davis');
$user->save();
$this->assertEquals('Miles Davis', $user->getFullName());
$this->unitTester->seeInDatabase('users', ['name' => 'Miles', 'surname' => 'Davis']);
$this->tester->seeInDatabase('users', ['name' => 'Miles', 'surname' => 'Davis']);
}
```

@@ -59,66 +59,64 @@ When you change the configuration, the actor classes are rebuilt automatically.
try to generate them manually with the `build` command:

```bash
php codecept build
php vendor/bin/codecept build
```

## Writing a Sample Scenario
## Writing a Sample Test

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 have created a file `tests/acceptance/SigninCept.php`

We can do that by running the following command:
Codeception has its own testing format called Cest (Codecept + Test).
To start writing a test we need to create a new Cest file. We can do that by running the following command:

```bash
php codecept generate:cept acceptance Signin
php vendor/bin/codecept generate:cest acceptance Signin
```

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 log in to our website:
This will generate `SigninCest.php` file inside `tests/acceptance` directory. Let's open it:

```php
<?php
$I = new AcceptanceTester($scenario); // actor class initialization
$I->wantTo('login to website');
```

The `wantTo` section describes your scenario in brief. There are additional comment methods that are useful to describe the context of a scenario:
class SigninCest
{
function _before(AcceptanceTester $I)
{
}
public function _after(AcceptanceTester $I)
{
}
```php
<?php
$I = new AcceptanceTester($scenario);
$I->am('user'); // actor's role
$I->wantTo('login to website'); // feature to test
$I->lookForwardTo('access website features for logged-in users'); // result to achieve
public function tryToTest(AcceptanceTester $I)
{
// todo: write test
}
}
```

After we have described the story background, let's start writing a scenario.
We have `_before` and `_after` methods to run some common actions before and after a test. And we have a placeholder action `tryToTest` which we need to implement.
If we try to test a signin process it's a good start to test a successful signin. Let's rename this method to `signInSuccessfully`.

We'll assume that we have a 'login' page where we get authenticated by providing a username and password.
We'll assume that we have a 'login' page where we get authenticated by providing a username and password.
Then we are sent to a user page, where we see the text `Hello, %username%`. Let's look at how this scenario is written in Codeception:

```php
<?php
$I = new AcceptanceTester($scenario);
$I->am('user');
$I->wantTo('login to website');
$I->lookForwardTo('access website features for logged-in users');
$I->amOnPage('/login');
$I->fillField('Username','davert');
$I->fillField('Password','qwerty');
$I->click('Login');
$I->see('Hello, davert');
class SigninCest
{
public function loginSuccessfully(AcceptanceTester $I)
{
$I->amOnPage('/login');
$I->fillField('Username','davert');
$I->fillField('Password','qwerty');
$I->click('Login');
$I->see('Hello, davert');
}
}
```

This scenario can probably be read by non-technical people. If you just remove all special chars like braces, arrows and `$`,
this test transforms into plain English text:

```
I am user
I wantTo login to website
I lookForwardTo access website features for logged-in users
I amOnPage '/login'
I fillField 'Username','davert'
I fillField 'Password','qwerty'
@@ -129,7 +127,7 @@ I see 'Hello, davert'
Codeception generates this text representation from PHP code by executing:

```bash
php codecept generate:scenarios
php vendor/bin/codecept generate:scenarios
```

These generated scenarios will be stored in your `_data` directory in text files.
@@ -149,14 +147,14 @@ modules:
After configuring the URL we can run this test with the `run` command:

```bash
php codecept run
php vendor/bin/codecept run
```

This is the output we should see:

```bash
Acceptance Tests (1) -------------------------------
SigninCept: Login to website
SigninCest: sign in successfully
----------------------------------------------------
Time: 1 second, Memory: 21.00Mb
@@ -167,19 +165,17 @@ OK (1 test, 1 assertions)
Let's get some detailed output:

```bash
php codecept run acceptance --steps
php vendor/bin/codecept run acceptance --steps
```

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

```bash
Acceptance Tests (1) -------------------------------
SigninCept: Login to website
Signature: SigninCept.php
Test: tests/acceptance/SigninCept.php
SigninCest: Login to website
Signature: SigninCest.php:signInSuccessfully
Test: tests/acceptance/SigninCest.php:signInSuccessfully
Scenario --
I am user
I look forward to access website features for logged-in users
I am on page "/login"
I fill field "Username" "davert"
I fill field "Password" "qwerty"
@@ -196,54 +192,43 @@ OK (1 test, 1 assertions)
This simple test can be extended to a complete scenario of site usage, therefore,
by emulating the user's actions, you can test any of your websites.

Give it a try!
To run more tests create a public method for each of them. Include `AcceptanceTester` object as `$I` as a method parameter and use the same `$I->` API you've seen before.
If your tests share common setup actions put them into `_before` method.

## Cept, Cest and Test Formats

Codeception supports three test formats. Beside the previously described scenario-based Cept format,
Codeception can also execute [PHPUnit test files for unit testing](http://codeception.com/docs/05-UnitTests), and Cest format.

**Cest** combines scenario-driven test approach with OOP design. In case you want to group a few testing scenarios into one, you should consider using Cest format.
In the example below we are testing CRUD actions within a single file but with several tests (one per operation):
For instance, to test CRUD we want 4 methods to be implemented and all next tests should start at `/task` page:

```php
<?php
class PageCrudCest
class TaskCrudCest
{
function _before(AcceptanceTester $I)
{
// will be executed at the beginning of each test
$I->amOnPage('/');
$I->amOnPage('/task');
}
function createPage(AcceptanceTester $I)
function createTask(AcceptanceTester $I)
{
// todo: write test
}
function viewPage(AcceptanceTester $I)
function viewTask(AcceptanceTester $I)
{
// todo: write test
}
function updatePage(AcceptanceTester $I)
function updateTask(AcceptanceTester $I)
{
// todo: write test
}
function deletePage(AcceptanceTester $I)
function deleteTask(AcceptanceTester $I)
{
// todo: write test
}
}
```

Cest files such as this can be created by running a generator:

```bash
php codecept generate:cest acceptance PageCrud
```

Learn more about the [Cest format](http://codeception.com/docs/07-AdvancedUsage#Cest-Classes) in the Advanced Testing section.

## BDD
@@ -262,44 +247,44 @@ The same goes for suite configs. For example, the `unit.suite.yml` will be merge
Tests can be started with the `run` command:

```bash
php codecept run
php vendor/bin/codecept run
```

With the first argument you can run all tests from one suite:

```bash
php codecept run acceptance
php vendor/bin/codecept run acceptance
```

To limit tests run to a single class, add a second argument. Provide a local path to the test class, from the suite directory:

```bash
php codecept run acceptance SigninCept.php
php vendor/bin/codecept run acceptance SigninCest.php
```

Alternatively you can provide the full path to test file:

```bash
php codecept run tests/acceptance/SigninCept.php
php vendor/bin/codecept run tests/acceptance/SigninCest.php
```

You can further filter which tests are run by appending a method name to the class, separated by a colon (for Cest or Test formats):

```bash
php codecept run tests/acceptance/SignInCest.php:^anonymousLogin$
php vendor/bin/codecept run tests/acceptance/SigninCest.php:^anonymousLogin$
```

You can provide a directory path as well. This will execute all acceptance tests from the `backend` dir:

```bash
php codecept run tests/acceptance/backend
php vendor/bin/codecept run tests/acceptance/backend
```

Using regular expressions, you can even run many different test methods from the same directory or class.
For example, this will execute all acceptance tests from the `backend` dir beginning with the word "login":

```bash
php codecept run tests/acceptance/backend:^login
php vendor/bin/codecept run tests/acceptance/backend:^login
```

To execute a group of tests that are not stored in the same directory, you can organize them in [groups](http://codeception.com/docs/07-AdvancedUsage#Groups).
@@ -309,15 +294,15 @@ To execute a group of tests that are not stored in the same directory, you can o
To generate JUnit XML output, you can provide the `--xml` option, and `--html` for HTML report.

```bash
php codecept run --steps --xml --html
php vendor/bin/codecept run --steps --xml --html
```

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

To see all the available options, run the following command:

```bash
php codecept help run
php vendor/bin/codecept help run
```

## Debugging
@@ -329,7 +314,6 @@ You may print any information inside a test using the `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:feature` *suite* *filename* - Generates Gherkin feature file
@@ -60,13 +60,23 @@ modules:
- \Helper\Acceptance
```

We should start by creating a 'Cept' file:
We should start by creating a test with the next command:

```
php vendor/bin/codecept g:cest acceptance Signin
```

It will be placed into `tests/acceptance` directory.

```php
<?php
// tests/acceptance/SigninCept.php
$I = new AcceptanceTester($scenario);
$I->wantTo('sign in');
class SigninCest
{
public function tryToTest(AcceptanceTester $I)
{
$I->wantTo('test my page');
}
}
```

The `$I` object is used to write all interactions.
@@ -203,7 +213,6 @@ you can pass instance `\Codeception\Step\Argument\PasswordArgument` with the dat

```php
<?php
<?php
use \Codeception\Step\Argument\PasswordArgument;
$I->amOnPage('/form/password_argument');
@@ -9,21 +9,21 @@ Codeception adds some nice helpers to simplify common tasks.
Create a test using `generate:test` command with a suite and test names as parameters:

```bash
php codecept generate:test unit Example
php vendor/bin/codecept generate:test unit Example
```

It creates a new `ExampleTest` file located in the `tests/unit` directory.

As always, you can run the newly created test with this command:

```bash
php codecept run unit ExampleTest
php vendor/bin/codecept run unit ExampleTest
```

Or simply run the whole set of unit tests with:

```bash
php codecept run unit
php vendor/bin/codecept run unit
```

A test created by the `generate:test` command will look like this:
@@ -73,15 +73,15 @@ class UserTest extends \Codeception\Test\Unit
{
public function testValidation()
{
$user = User::create();
$user = new User();
$user->username = null;
$user->setName(null);
$this->assertFalse($user->validate(['username']));
$user->username = 'toolooooongnaaaaaaameeee';
$user->setName('toolooooongnaaaaaaameeee');
$this->assertFalse($user->validate(['username']));
$user->username = 'davert';
$user->setName('davert');
$this->assertTrue($user->validate(['username']));
}
}

0 comments on commit 5438396

Please sign in to comment.
You can’t perform that action at this time.