Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 4 additions & 6 deletions docs/APITesting.md
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,7 @@ We will put all the api tests there.

> **NOTE:** REST API testing requires the `codeception/module-rest` package to be installed.

The REST web service is accessed via HTTP with standard methods: `GET`, `POST`, `PUT`, `DELETE`. They allow users to receive and manipulate entities from the service. Accessing a WebService requires an HTTP client, so for using it you need the module `PhpBrowser` or one of framework modules set up. For example, we can use the `Symfony` module for Symfony2 applications in order to ignore web server and test web service internally.
The REST web service is accessed via HTTP with standard methods: `GET`, `POST`, `PUT`, `DELETE`. They allow users to receive and manipulate entities from the service. Accessing a WebService requires an HTTP client, so for using it you need the module `PhpBrowser` or one of framework modules set up. For example, we can use the `Symfony` module for Symfony applications in order to ignore web server and test web service internally.

Configure modules in `Api.suite.yml`:

Expand Down Expand Up @@ -137,8 +137,6 @@ To send a request with custom method use `send` action:
$response = $I->send('TRACE', '/posts');
```

> sendAsJson methods were introduced in module-rest 1.4.1

If API endpoint accepts JSON you can use `send` methods with `AsJson` suffix to convert data automatically.
In this case `Content-Type` header is sent with `application/json` value and response if JSON is parsed:

Expand Down Expand Up @@ -249,7 +247,7 @@ class Api extends \Codeception\Module
public function seeResponseIsHtml()
{
$response = $this->getModule('REST')->response;
$this->assertRegExp('~^<!DOCTYPE HTML(.*?)<html>.*?<\/html>~m', $response);
$this->assertMatchesRegularExpression('~^<!DOCTYPE HTML(.*?)<html>.*?<\/html>~m', $response);
}
}

Expand Down Expand Up @@ -361,7 +359,7 @@ $I->seeSoapResponseIncludes(\Codeception\Util\Xml::build()

It's up to you to decide whether to use `XmlBuilder` or plain XML. `XmlBuilder` will return XML string as well.

You may extend current functionality by using `SOAP` module in your helper class. To access the SOAP response as `\DOMDocument` you can use `response` property of `SOAP` module.
You may extend current functionality by using `SOAP` module in your helper class. To access the SOAP response as `\DOMDocument` you can use `xmlResponse` property of `SOAP` module.

```php
<?php
Expand All @@ -370,7 +368,7 @@ class Api extends \Codeception\Module {

public function seeResponseIsValidOnSchema($schema)
{
$response = $this->getModule('SOAP')->response;
$response = $this->getModule('SOAP')->xmlResponse;
$this->assertTrue($response->schemaValidate($schema));
}
}
Expand Down
2 changes: 1 addition & 1 deletion docs/AcceptanceTests.md
Original file line number Diff line number Diff line change
Expand Up @@ -462,7 +462,7 @@ It is important to understand that SmartWait works only with a specific locators

* `#locator` - CSS ID locator, works
* `//locator` - general XPath locator, works
* `['css' => 'button'']` - strict locator, works
* `['css' => 'button']` - strict locator, works

But it won't be executed for all other locator types.
See the example:
Expand Down
21 changes: 10 additions & 11 deletions docs/AdvancedUsage.md
Original file line number Diff line number Diff line change
Expand Up @@ -208,7 +208,7 @@ The concept of groups was taken from PHPUnit and behaves in the same way. You ca
namespace Tests\Acceptance;

use Codeception\Attribute\Group;
use Tests\Support\AcceptanceTester
use Tests\Support\AcceptanceTester;

class UserCest
{
Expand Down Expand Up @@ -285,7 +285,7 @@ class EndpointCest

## Example Annotation

As well as the `\Codeception\Attribute\Examples` attribute, available for Cest tests, the `@example` attribute allows you to
As well as the `\Codeception\Attribute\Examples` attribute, available for Cest tests, the `@example` annotation allows you to
inject test parameters in place of an actual [DataProvider](#dataprovider-attribute) for Unit tests.

```php
Expand All @@ -311,7 +311,7 @@ class ExampleTest extends \Codeception\Test\Unit

## DataProvider Attribute

You can also use the `@dataProvider` annotation for creating dynamic examples for [Cest classes](#Cest-Classes), using a **protected method** for providing example data:
You can also use the `#[DataProvider]` attribute for creating dynamic examples for [Cest classes](#Cest-Classes), using a **protected method** for providing example data:

```php
<?php
Expand Down Expand Up @@ -383,7 +383,7 @@ final class ModeratorCest

// But you can also pass multiple methods in each attribute:
#[Before('login', 'cleanup')]
public function addUser(FunctionalTester $I): void
public function addAdmin(FunctionalTester $I): void
{
// ...
}
Expand Down Expand Up @@ -424,7 +424,7 @@ Normally, the test signature matches the `className:methodName` format.
But to get the exact test signature just run the test with the `--steps` option to see it:

```
Signature: ModeratorCest:login`
Signature: ModeratorCest:login
```

Codeception reorders tests so dependent tests will always be executed before the tests that rely on them.
Expand Down Expand Up @@ -502,7 +502,7 @@ To run the tests in all browsers, list all the environments:
php vendor/bin/codecept run Acceptance --env chrome --env firefox
```

The tests will be executed 3 times, each time in a different browser.
The tests will be executed 2 times, each time in a different browser.

It's also possible to merge multiple environments into a single configuration by separating them with a comma:

Expand Down Expand Up @@ -586,7 +586,7 @@ $scenario->current('capabilities');
You can inject `\Codeception\Scenario` like this:

```php
use Codeception\Scenario $scenario;
use Codeception\Scenario;

public function myTest(Scenario $scenario)
{
Expand Down Expand Up @@ -622,10 +622,9 @@ codecept run -o "settings: shuffle: true"
Tests will be randomly reordered on each run. When tests are executed in shuffle mode a seed value will be printed.
Copy this seed value from the output to be able to rerun tests in the same order.

```yaml
```bash
$ codecept run
Codeception PHP Testing Framework v2.4.5
Powered by PHPUnit 5.7.27 by Sebastian Bergmann and contributors.
Codeception PHP Testing Framework v5.3.7 https://stand-with-ukraine.pp.ua
[Seed] 1872290562
```

Expand All @@ -644,7 +643,7 @@ passing all dependencies as arguments. This may be useful when working with Help

```php
<?php
namespace Tests\Unit;
namespace Tests\Acceptance;

use Tests\Support\AcceptanceTester;
use Tests\Support\Helper\SignUp;
Expand Down
6 changes: 3 additions & 3 deletions docs/BDD.md
Original file line number Diff line number Diff line change
Expand Up @@ -225,7 +225,7 @@ public function amAuthorized($role)
Parameters can be also passed in non-regex strings using ":" params placeholder.

```php
#[Given('Given I am logged in as :role')
#[Given('I am logged in as :role')]
```

This will match any word (passed in double quotes) or a number passed:
Expand Down Expand Up @@ -399,7 +399,7 @@ Tables is a recommended ways to pass arrays into test scenarios.
Inside a step definition data is stored in argument passed as `\Behat\Gherkin\Node\TableNode` instance.

```php
#[Given('i have products in my cart')
#[Given('i have products in my cart')]
public function iHaveProductsInCart(\Behat\Gherkin\Node\TableNode $products)
{
// iterate over all rows
Expand Down Expand Up @@ -452,7 +452,7 @@ paths:
This string is passed as a standard PHP string parameter

```php
#[Then('i see in file :filename')
#[Then('i see in file :filename')]
public function seeInFile($fileName, $fileContents)
{
// note: module "Asserts" is enabled in this suite
Expand Down
6 changes: 3 additions & 3 deletions docs/Codecoverage.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@ The required information is provided by [SebastianBergmann\CodeCoverage](https:/
| Driver | Description |
| --- | --- |
| [Xdebug](https://github.com/xdebug/xdebug) | Great for debugging, but too slow when collecting coverage |
| [phpdbg](https://www.php.net/manual/en/book.phpdbg.php) | Faster than `Xdebug` but inaccurate |
| [phpdbg](https://www.php.net/manual/en/book.phpdbg.php) | Faster than `Xdebug` but inaccurate. Only supported with PHPUnit 9 |
| [pcov](https://github.com/krakjoe/pcov) | Fast and accurate, but no debug functionality &mdash; perfect for CI |

![Code Coverage Example](https://codeception.com/images/coverage.png)
Expand Down Expand Up @@ -63,7 +63,7 @@ coverage:
high_limit: 60
```

By default, show all whitelisted files in `--coverage-text` output not just the ones with coverage information is set to false, config option:
By default, `--coverage-text` output only shows files with coverage information. To show all included files, set `show_uncovered` to `true` (default: `false`):


```yaml
Expand Down Expand Up @@ -108,7 +108,7 @@ XML clover reports are used by IDEs (like PHPStorm) or Continuous Integration se

If you run your application via Webserver (Apache, Nginx, PHP WebServer) you don't have a direct access to tested code,
so collecting coverage becomes a non-trivial task. The same goes for scripts that are tested on different nodes.
To get access to this code you need `xdebug` installed with `remote_enable` option turned on.
To get access to this code you need a coverage driver on the server: `pcov` or `xdebug` with coverage enabled (`xdebug.mode=coverage`). Path coverage (`path_coverage: true`) requires `xdebug`.
Codeception also requires a little spy to interact with your application. As your application runs standalone,
without even knowing it is being tested, a small file should be included in order to collect coverage info.

Expand Down
28 changes: 8 additions & 20 deletions docs/ContinuousIntegration.md
Original file line number Diff line number Diff line change
Expand Up @@ -49,11 +49,11 @@ Then we can start the very first job and check the execution progress. If tests

### XML Reports

But we don't want to analyze console output for each failing build. Especially If Jenkins can collect and display the results inside its web UI. Codeception can export its results using JUnit XML format. To generate XML report on each build we will need to append `--xml` option to Codeception execution command. Codeception will print `result.xml` file containing information about test status with steps and stack traces for failing tests.
But we don't want to analyze console output for each failing build. Especially If Jenkins can collect and display the results inside its web UI. Codeception can export its results using JUnit XML format. To generate XML report on each build we will need to append `--xml` option to Codeception execution command. Codeception will print `report.xml` file into `tests/_output` containing information about test status with steps and stack traces for failing tests.

Now let's update our build step to generate xml:

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

Expand All @@ -71,7 +71,7 @@ Now for all builds we will see results trend graph that shows us percentage of p

To get more details on steps executed you can generate HTML report and use Jenkins to display them.

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

Expand Down Expand Up @@ -101,11 +101,11 @@ jobs:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v2
uses: actions/checkout@v4
- name: Install PHP
uses: shivammathur/setup-php@v2
with:
php-version: ${{ matrix.php }}
php-version: '8.4'
extensions: curl, mbstring, openssl, pdo, pdo_sqlite
ini-values: memory_limit=-1, date.timezone='UTC'
coverage: xdebug
Expand All @@ -115,7 +115,7 @@ jobs:
run: composer validate

- name: Install dependencies
run: composer install --prefer-dist --no-progress --no-interaction --no-suggest
run: composer install --prefer-dist --no-progress --no-interaction

- name: Run tests
run: php vendor/bin/codecept run
Expand All @@ -125,11 +125,11 @@ jobs:

![report](https://codeception.com/images/gitlab/logo.png)

If a file `.gitlab-ci.yml` exists in the root of the git repository, GitLab will run a pipeline each time you push to the gitlab server. The file configures the docker image that will be called. Below is a sample which loads a php7 docker image, clones your files, installs composer dependencies, runs the built-in php webserver and finally runs codeception:
If a file `.gitlab-ci.yml` exists in the root of the git repository, GitLab will run a pipeline each time you push to the gitlab server. The file configures the docker image that will be called. Below is a sample which loads a PHP 8.4 docker image, clones your files, installs composer dependencies, runs the built-in php webserver and finally runs codeception:

```yaml
# Select image from https://hub.docker.com/_/php/
image: php:7.0
image: php:8.4

# Select what we should cache
cache:
Expand Down Expand Up @@ -189,16 +189,4 @@ test:
junit: tests/_output/report.xml
```

## TravisCI

![Travis CI](https://codeception.com/images/travis.png)

Travis CI is popular service CI with good GitHub integration. Codeception is self-tested with Travis CI. There nothing special about configuration. Just add to the bottom line of travis configuration:

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

Travis doesn't provide visualization for XML or HTML reports so you can't view reports in format any different than console output. However, Codeception produces nice console output with detailed error reports.

<div class="alert alert-warning"><a href="https://github.com/Codeception/codeception.github.com/edit/master/docs/ContinuousIntegration.md"><strong>Improve</strong> this guide</a></div>
41 changes: 20 additions & 21 deletions docs/Customization.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,10 +19,10 @@ php vendor/bin/codecept bootstrap --namespace frontend
```

This will bootstrap a new project with the `namespace: frontend` parameter in the `codeception.yml` file.
Helpers will be in the `frontend\Codeception\Module` namespace and Actor classes will be in the `frontend` namespace.
Actor classes will be in the `frontend\Support` namespace and Helpers will be in the `frontend\Support\Helper` namespace.

Once each of your applications (bundles) has its own namespace and different Helper or Actor classes,
you can execute all the tests in a single runner. Run the Codeception tests as usual, using the meta-config we created earlier:
you can execute all the tests in a single runner. Run the Codeception tests as usual, using a meta-config which [includes all applications](#One-Runner-for-Multiple-Applications):

```bash
php vendor/bin/codecept run
Expand Down Expand Up @@ -137,9 +137,10 @@ All listed events are available as constants in `Codeception\Events` class.
| `result.print.after` | After result was printed | [Result, Printer](https://github.com/Codeception/Codeception/blob/5.0/src/Codeception/Event/PrintResultEvent.php)

There may be some confusion between `test.start`/`test.before` and `test.after`/`test.end`.
The start and end events are triggered by PHPUnit, but the before and after events are triggered by Codeception.
Thus, when you are using classical PHPUnit tests (extended from `PHPUnit\Framework\TestCase`),
the before/after events won't be triggered for them. During the `test.before` event you can mark a test
The start and end events are triggered by the suite around each test, while the before and after events are triggered
from inside the test and are also dispatched per group (see [Group Objects](#Group-Objects)).
All of them are triggered for every kind of test, including classical PHPUnit tests (extended from `PHPUnit\Framework\TestCase`).
During the `test.before` event you can mark a test
as skipped or incomplete, which is not possible in `test.start`. You can learn more from
[Codeception internal event listeners](https://github.com/Codeception/Codeception/tree/5.0/src/Codeception/Subscriber).

Expand Down Expand Up @@ -183,13 +184,13 @@ Extensions have some basic methods you can use:
* `writeln` - prints to the screen with a new-line character at the end
* `getModule` - allows you to access a module
* `hasModule` - checks if a module is enabled
* `getModuleNames` - list all enabled modules
* `getCurrentModuleNames` - list all enabled modules
* `_reconfigure` - can be implemented instead of overriding the constructor

### Enabling Extension

Once you've implemented a simple extension class, you can require it in `tests/_bootstrap.php`,
load it with Composer's autoloader defined in `composer.json`, or store the class inside `tests/Support`dir.
Once you've implemented a simple extension class, you can require it in a [bootstrap file](#Bootstrap),
load it with Composer's autoloader defined in `composer.json`, or store the class inside `tests/Support` dir.

You can then enable it in `codeception.yml`

Expand Down Expand Up @@ -271,8 +272,6 @@ public function testAdminCreatingNewBlogPost(AcceptanceTester $I)
This test will trigger the following events:

* `test.before.admin`
* `step.before.admin`
* `step.after.admin`
* `test.success.admin`
* `test.fail.admin`
* `test.after.admin`
Expand All @@ -281,7 +280,7 @@ A group object is built to listen for these events. It is useful when an additio
for some of your tests. Let's say you want to load fixtures for tests that belong to the `admin` group:
```php
<?php
namespace Group;
namespace Tests\Support\Group;

class Admin extends \Codeception\GroupObject
{
Expand Down Expand Up @@ -319,14 +318,14 @@ For instance, for `nocleanup` group we prevent Doctrine module from wrapping tes

```

A group class can be created with `php vendor/bin/codecept generate:group groupname` command.
A group class can be created with `php vendor/bin/codecept generate:groupobject groupname` command.
Group classes will be stored in the `tests/Support/Group` directory.

A group class can be enabled just like you enable an extension class. In the file `codeception.yml`:

```yaml
extensions:
enabled: [Group\Admin]
enabled: [Tests\Support\Group\Admin]

```

Expand All @@ -347,13 +346,13 @@ List of available step decorators:
- [TryTo](https://github.com/Codeception/Codeception/blob/5.0.0/src/Codeception/Step/TryTo.php) - failed action will be ignored.
- [Retry](https://github.com/Codeception/Codeception/blob/5.0.0/src/Codeception/Step/Retry.php) - failed action will be retried automatically.

Step decorators can be added to suite config inside `steps` block:
Step decorators can be added to suite config inside `step_decorators` block:

```yaml
step_decorators:
- Codeception/Step/TryTo
- Codeception/Step/Retry
- Codeception/Step/ConditionalAssertion
- Codeception\Step\TryTo
- Codeception\Step\Retry
- Codeception\Step\ConditionalAssertion

```

Expand Down Expand Up @@ -459,17 +458,17 @@ class MyFormat implements \Codeception\Test\Loader\LoaderInterface
$this->settings = $settings;
}

public function loadTests($filename)
public function loadTests(string $filename): void
{
//Load file and create tests
}

public function getTests()
public function getTests(): array
{
return $this->tests;
}

public function getPattern()
public function getPattern(): string
{
return '~Myformat\.php$~';
}
Expand Down Expand Up @@ -535,7 +534,7 @@ settings:

```

You should also specify the path to the `log` directory, where the reports and logs will be saved.
You should also specify the path to the `output` directory, where the reports and logs will be saved.

> Wildcards (`*`) can be used to specify multiple directories at once.

Expand Down
Loading