updated docs, removed mentions of Cept format

Codeception · Mar 31, 2018 · 5438396 · 5438396
1 parent 853683f
commit 5438396
Show file tree

Hide file tree

Showing 10 changed files with 137 additions and 144 deletions.
diff --git a/docs/01-Introduction.md b/docs/01-Introduction.md
@@ -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']);
 }
 ```
 

diff --git a/docs/02-GettingStarted.md b/docs/02-GettingStarted.md
@@ -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

diff --git a/docs/03-AcceptanceTests.md b/docs/03-AcceptanceTests.md
@@ -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');

diff --git a/docs/05-UnitTests.md b/docs/05-UnitTests.md
@@ -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']));
     }
 }