Skip to content

Commit eab48b0

Browse files
NaktibaldaNaktibalda
committed
Copy Codeception 4 guides from 4.x tag
1 parent 4df4064 commit eab48b0

15 files changed

+6990
-0
lines changed

‎docs/4.x/01-Introduction.md

Lines changed: 137 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,137 @@
1+
---
2+
layout: doc
3+
title: 01-Introduction - Codeception - Documentation
4+
---
5+
6+
# Introduction
7+
8+
The idea behind testing is not new. You can't sleep well if you are not confident
9+
that your latest commit didn't take down the entire application.
10+
Having your application covered with tests gives you more trust in the stability of your application. That's all.
11+
12+
In most cases tests don't guarantee that the application works 100% as it is supposed to.
13+
You can't predict all possible scenarios and exceptional situations for complex apps,
14+
but with tests you can cover the most important parts of your app and at least be sure they work as predicted.
15+
16+
There are plenty of ways to test your application.
17+
The most popular paradigm is [Unit Testing](https://en.wikipedia.org/wiki/Unit_testing).
18+
For web applications, testing just the controller and/or the model doesn't prove that your application is working.
19+
To test the behavior of your application as a whole, you should write functional or acceptance tests.
20+
21+
Codeception supports all three testing types.
22+
Out of the box you have tools for writing unit, functional, and acceptance tests in a unified framework.
23+
24+
| | Unit Tests | Functional Tests | Acceptance Tests
25+
| --- | --- | --- | --- |
26+
| Scope of the test | Single PHP class | PHP Framework (Routing, Controllers, etc.) | Page in browser (Chrome, Firefox, or [PhpBrowser](https://codeception.com/docs/03-AcceptanceTests#PhpBrowser)) |
27+
| Testing computer needs access to project's PHP files | Yes | Yes | No |
28+
| Webserver required | No | No | Yes |
29+
| JavaScript | No | No | Yes |
30+
| Additional software required | None | None | Selenium for browser testing |
31+
| Speed | Fast | Fast | Slow |
32+
| Configuration file | `unit.suite.yml` | `functional.suite.yml` | `acceptance.suite.yml` |
33+
34+
One of the main advantages of Codeception is that you don't have to decide on just *one* type of testing. You should have all three!
35+
And chances are, that you will (sooner or later) need all three. That's why Codeception consists of three so-called "suites":
36+
A "unit suite" for all unit tests, a "functional suite" for all functional tests, and an "acceptance suite" for all acceptance tests.
37+
38+
Let's review those three testing types in reverse order.
39+
40+
### Acceptance Tests
41+
42+
How does your client, manager, tester, or any other non-technical person know your website is working? By opening the browser, accessing the site, clicking on links, filling in the forms, and actually seeing the content on a web page. They have no idea of the programming language, framework, database, web-server,
43+
or why the application did (or did not) behave as expected.
44+
45+
This is what acceptance tests are doing. They cover scenarios from a user's perspective.
46+
With acceptance tests, you can be confident that users, following all the defined scenarios, won't get errors.
47+
48+
> **Any website** can be covered with acceptance tests, even if you use a very exotic CMS or framework.
49+
50+
#### Sample acceptance test
51+
52+
{% highlight php %}
53+
54+
<?php
55+
$I->amOnPage('/');
56+
$I->click('Sign Up');
57+
$I->submitForm('#signup', [
58+
'username' => 'MilesDavis',
59+
'email' => 'miles@davis.com'
60+
]);
61+
$I->see('Thank you for Signing Up!');
62+
63+
{% endhighlight %}
64+
65+
### Functional Tests
66+
67+
What if you could check our application without running it on a server?
68+
That way you could see detailed exceptions on errors, have our tests run faster, and check the database against predictable and expected results. That's what functional tests are for.
69+
70+
For functional tests, you emulate a web request (`$_GET` and `$_POST` variables) which returns the HTML response. Inside a test, you can make assertions about the response, and you can check if the data was successfully stored in the database.
71+
72+
For functional tests, your application needs to be structured in order to run in a test environment. Codeception provides connectors to all popular PHP frameworks.
73+
74+
#### Sample functional test
75+
76+
{% highlight php %}
77+
78+
<?php
79+
$I->amOnPage('/');
80+
$I->click('Sign Up');
81+
$I->submitForm('#signup', ['username' => 'MilesDavis', 'email' => 'miles@davis.com']);
82+
$I->see('Thank you for Signing Up!');
83+
$I->seeEmailSent('miles@davis.com', 'Thank you for registration');
84+
$I->seeInDatabase('users', ['email' => 'miles@davis.com']);
85+
86+
{% endhighlight %}
87+
88+
> This looks very similar to acceptance tests. The behavior is the same, however, the test is executed inside PHP without launching a browser.
89+
90+
### Unit Tests
91+
92+
Testing pieces of code before coupling them together is highly important as well. This way,
93+
you can be sure that some deeply hidden feature still works, even if it was not covered by functional or acceptance tests.
94+
This also shows care in producing stable and testable code.
95+
96+
Codeception is created on top of [PHPUnit](https://www.phpunit.de/). If you have experience writing unit tests with PHPUnit
97+
you can continue doing so. Codeception has no problem executing standard PHPUnit tests,
98+
but, additionally, Codeception provides some well-built tools to make your unit tests simpler and cleaner.
99+
100+
Requirements and code can change rapidly,
101+
and unit tests should be updated every time to fit the requirements.
102+
The better you understand the testing scenario, the faster you can update it for new behavior.
103+
104+
#### Sample integration test
105+
106+
{% highlight php %}
107+
108+
<?php
109+
public function testSavingUser()
110+
{
111+
$user = new User();
112+
$user->setName('Miles');
113+
$user->setSurname('Davis');
114+
$user->save();
115+
$this->assertEquals('Miles Davis', $user->getFullName());
116+
$this->tester->seeInDatabase('users', [
117+
'name' => 'Miles',
118+
'surname' => 'Davis'
119+
]);
120+
}
121+
122+
{% endhighlight %}
123+
124+
## Conclusion
125+
126+
The Codeception framework was developed to actually make testing fun.
127+
It allows writing unit, functional, integration, and acceptance tests in a single, coherent style.
128+
129+
All Codeception tests are written in a descriptive manner.
130+
Just by looking at the test body, you can clearly understand what is being tested and how it is performed.
131+
132+
133+
134+
135+
* **Next Chapter: [GettingStarted >](/docs/02-GettingStarted)**
136+
137+
<div class="alert alert-warning"><a href="https://github.com/Codeception/codeception.github.com/edit/master/docs/01-Introduction.md"><strong>Edit</strong> this page on GitHub</a></div>

0 commit comments

Comments
 (0)