diff --git a/docs/APITesting.md b/docs/APITesting.md index 3e1bac17d..8ac1f0060 100644 --- a/docs/APITesting.md +++ b/docs/APITesting.md @@ -34,7 +34,7 @@ modules: depends: PhpBrowser ``` -The REST module will connect to `PhpBrowser` according to this configuration. Depending on the web service we may deal with XML or JSON responses. Codeception handles both data formats well, however If you don't need one of them, you can explicitly specify that the JSON or XML parts of the module will be used: +The REST module will connect to `PhpBrowser` according to this configuration. Depending on the web service we may deal with XML or JSON responses. Codeception handles both data formats well, however, if you don't need one of them, you can explicitly specify that the JSON or XML parts of the module will be used: ```yaml actor: ApiTester @@ -46,7 +46,7 @@ modules: part: Json ``` -API tests can be functional and be executed using Symfony, Laravel, Yii2, or any other framework module. You will need slightly update configuration for it: +API tests can be functional and be executed using Symfony, Laravel, Yii2, or any other framework module. You will need to slightly update the configuration for it: ```yaml actor: ApiTester @@ -160,7 +160,7 @@ and rebuild actions: php vendor/bin/codecept build ``` -> `sendGetAsJson`, `sendPutAsJson`, and others, are implemented as a [Step Decorator](https://codeception.com/docs/08-Customization#Step-Decorators). +> `sendGetAsJson`, `sendPutAsJson`, and others, are implemented as a [Step Decorator](https://codeception.com/docs/Customization#Step-Decorators). ### JSON Structure Validation @@ -177,7 +177,7 @@ $I->seeResponseJsonMatchesXpath('//user/login'); ``` More detailed check can be applied if you need to validate the type of fields in a response. -You can do that by using with a [seeResponseMatchesJsonType](https://codeception.com/docs/modules/REST#seeResponseMatchesJsonType) action in which you define the structure of JSON response. +You can do that by using a [seeResponseMatchesJsonType](https://codeception.com/docs/modules/REST#seeResponseMatchesJsonType) action in which you define the structure of JSON response. ```php sendGet('/users'); @@ -210,9 +211,10 @@ $users = $I->sendGet('/users'); $users = $I->grabResponse(); ``` -When you need to obtain a value from a response and use it in next requests you can use `grab*` methods. For instance, use `grabDataFromResponseByJsonPath` allows to query JSON for a value. +When you need to obtain a value from a response and use it in subsequent requests, you can use `grab*` methods. For instance, `grabDataFromResponseByJsonPath` allows querying JSON for a value. -```phpgrabDataFromResponseByJsonPath('$.id'); $I->sendGet('/pet/' . $id); ``` @@ -223,7 +225,7 @@ The last line of the previous example verified that the response contained the p ```php seeResponseContainsJson(['result' => 'ok']); // it can match tree-like structures as well $I->seeResponseContainsJson([ @@ -236,7 +238,7 @@ $I->seeResponseContainsJson([ ``` -You may want to perform even more complex assertions on a response. This can be done by writing your own methods in the [Helper](https://codeception.com/docs/06-ReusingTestCode#Modules-and-Helpers) classes. To access the latest JSON response you will need to get the `response` property of the `REST` module. Let's demonstrate it with the `seeResponseIsHtml` method: +You may want to perform even more complex assertions on a response. This can be done by writing your own methods in the [Helper](https://codeception.com/docs/ModulesAndHelpers#Helpers) classes. To access the latest JSON response you will need to get the `response` property of the `REST` module. Let's demonstrate it with the `seeResponseIsHtml` method: ```php ` element of XML request. In case you need to submit such header, you can use `haveSoapHeader` action. For example, next line of code @@ -335,7 +337,7 @@ And here is the list of sample assertions that can be used with SOAP. ```php seeSoapResponseEquals('500'); +$I->seeSoapResponseEquals('500'); $I->seeSoapResponseIncludes('1'); $I->seeSoapResponseContainsStructure(''); $I->seeSoapResponseContainsXPath('//result/user/name[@id=1]'); @@ -348,7 +350,7 @@ In the next example we will use `XmlBuilder` instead of regular XML. ```php haveSoapHeader('Session', array('token' => '123456')); -$I->sendSoapRequest('CreateUser', Xml::build() +$I->sendSoapRequest('CreateUser', \Codeception\Util\Xml::build() ->user->email->val('miles@davis.com')); $I->seeSoapResponseIncludes(\Codeception\Util\Xml::build() ->result->val('Ok') diff --git a/docs/AcceptanceTests.md b/docs/AcceptanceTests.md index 6faee3631..d4d40d3b9 100644 --- a/docs/AcceptanceTests.md +++ b/docs/AcceptanceTests.md @@ -47,7 +47,7 @@ We will start writing our first acceptance tests with PhpBrowser. This is the fastest way to run acceptance tests since it doesn't require running an actual browser. We use a PHP web scraper, which acts like a browser: It sends a request, then receives and parses the response. -Codeception uses [Guzzle](https://guzzlephp.org) and [Symfony BrowserKit](https://symfony.com/doc/current/components/browser_kit.html) to interact with HTML web pages. +Codeception uses [Guzzle](https://docs.guzzlephp.org/) and [Symfony BrowserKit](https://symfony.com/doc/current/components/browser_kit.html) to interact with HTML web pages. Common PhpBrowser drawbacks: @@ -74,6 +74,12 @@ php vendor/bin/codecept g:cest Acceptance Signin It will be placed into `tests/Acceptance` directory. ```php +click('Log in'); // CSS selector applied $I->click('#login a'); // XPath -$I->click('//a[@id=login]'); +$I->click('//a[@id="login"]'); // Using context as second argument $I->click('Login', '.nav'); ``` @@ -343,7 +349,7 @@ $user_id = $I->grabFromCurrentUrl('~^/user/(\d+)/~'); ## WebDriver -A nice feature of Codeception is that most scenarios are similar, no matter of how they are executed. +A nice feature of Codeception is that most scenarios are similar, no matter how they are executed. `PhpBrowser` was emulating browser requests but how to execute such test in a real browser like Chrome or Firefox? Selenium WebDriver can drive them so in our acceptance tests we can automate scenarios we used to test manually. In such tests, we should concentrate more on **testing the UI** than on testing functionality. @@ -376,13 +382,13 @@ Launch this command in a separate terminal: selenium-standalone start ``` -![](https://raw.githubusercontent.com/vvo/selenium-standalone/HEAD/screencast.gif) +![](https://raw.githubusercontent.com/webdriverio/selenium-standalone/HEAD/screencast.gif) Now, you are ready to run WebDriver tests using Codeception. > Alternatively, Selenium Server can be installed manually. [Download it](https://www.selenium.dev/downloads/) from the official site and launch a server with Java: `java -jar selenium-server-....jar`. In this case ChromeDriver and GeckoDriver must be installed separately. -* For more information refer to [Installation Instructions](https://codeception.com/docs/modules/WebDriver#Selenium) +* For more information refer to [Installation Instructions](https://codeception.com/docs/modules/WebDriver#Selenium-Recommended) * Enable [RunProcess](https://codeception.com/extensions#RunProcess) extension to start/stop Selenium automatically *(optional)*. @@ -397,7 +403,7 @@ actor: AcceptanceTester modules: enabled: - WebDriver: - url: {{your site URL}} + url: http://localhost/myapp browser: chrome ``` @@ -415,7 +421,7 @@ WebDriver also adds browser-specific functionality: #### Wait -While testing web application, you may need to wait for JavaScript events to occur. Due to its asynchronous nature, +While testing a web application, you may need to wait for JavaScript events to occur. Due to its asynchronous nature, complex JavaScript interactions are hard to test. That's why you may need to use waiters, actions with `wait` prefix. They can be used to specify what event you expect to occur on a page, before continuing the test. @@ -430,7 +436,7 @@ In this case, we are waiting for the 'agree' button to appear and then click it. the test will fail. There are other `wait` methods you may use, like [waitForText](https://codeception.com/docs/modules/WebDriver#waitForText), [waitForElementVisible](https://codeception.com/docs/modules/WebDriver#waitForElementVisible) and others. -If you don't know what exact element you need to wait for, you can simply pause execution with using `$I->wait()` +If you don't know what exact element you need to wait for, you can simply pause execution by using `$I->wait()` ```php $I->wait(3); // wait for 3 secs @@ -438,9 +444,9 @@ $I->wait(3); // wait for 3 secs #### SmartWait -It is possible to wait for elements pragmatically. -If a test uses element which is not on a page yet, Codeception will wait for few extra seconds before failing. -This feature is based on [Implicit Wait](https://www.seleniumhq.org/docs/04_webdriver_advanced.jsp#implicit-waits) of Selenium. +It is possible to wait for elements programmatically. +If a test uses an element which is not on a page yet, Codeception will wait for a few extra seconds before failing. +This feature is based on [Implicit Wait](https://www.selenium.dev/documentation/webdriver/waits/#implicit-waits) of Selenium. Codeception enables implicit wait only when searching for a specific element and disables in all other cases. Thus, the performance of a test is not affected. SmartWait can be enabled by setting `wait` option in WebDriver config. It expects the number of seconds to wait. Example: @@ -458,7 +464,7 @@ With this config we have the following test: $I->click(['css' => '#click-me']); ``` -It is important to understand that SmartWait works only with a specific locators: +It is important to understand that SmartWait works only with specific locators: * `#locator` - CSS ID locator, works * `//locator` - general XPath locator, works @@ -480,9 +486,9 @@ $I->seeNumberOfElements(['css' => 'button.link'], 5); // DISABLED, can wait only #### Retry -When it's hard to define condition to wait for, we can retry a command few times until it succeeds. -For instance, if you try to click while it's animating you can try to do it few times until it freezes. -Each action and assertion have an alias prefixed with `retry` which allows to retry a flaky command. +When it's hard to define a condition to wait for, we can retry a command a few times until it succeeds. +For instance, if you try to click while it's animating you can try to do it a few times until it freezes. +Each action and assertion has an alias prefixed with `retry` which allows to retry a flaky command. ```php $I->retryClick('flaky element'); @@ -552,11 +558,11 @@ For more options see [`performOn()` reference](https://codeception.com/docs/modu #### A/B Testing -When a web site acts unpredictably you may need to react on that change. -This happens if site configured for A/B testing, or shows different popups, based on environment. +When a web site acts unpredictably you may need to react to that change. +This happens if a site is configured for A/B testing, or shows different popups, based on environment. Since Codeception 3.0 you can have some actions to fail silently, if they are errored. -Let's say, you open a page and some times there is a popup which should be closed. +Let's say, you open a page and sometimes there is a popup which should be closed. We may try to hit the "close" button but if this action fails (no popup on page) we just continue the test. This is how it can be implemented: @@ -634,7 +640,7 @@ class AcceptanceTester extends \Codeception\Actor ### Cloud Testing -Some environments are hard to be reproduced manually, testing Internet Explorer 6-8 on Windows XP may be a hard thing, +Some environments are hard to reproduce manually, testing Internet Explorer 6-8 on Windows XP may be a hard thing, especially if you don't have Windows XP installed. This is where Cloud Testing services come to help you. Services such as [SauceLabs](https://saucelabs.com), [BrowserStack](https://www.browserstack.com/) and [others](https://codeception.com/docs/modules/WebDriver#Cloud-Testing) can create virtual machines on demand @@ -650,12 +656,12 @@ You just need to set the [WebDriver configuration](https://codeception.com/docs/ * browser * OS -We recommend using [params](https://codeception.com/docs/06-ModulesAndHelpers#Dynamic-Configuration-With-Params) +We recommend using [params](https://codeception.com/docs/ModulesAndHelpers#Dynamic-Configuration-With-Parameters) to provide authorization credentials. It should be mentioned that Cloud Testing services are not free. You should investigate their pricing models and choose one that fits your needs. They also may work painfully slowly if ping times between the local server -and the cloud is too high. This may lead to random failures in acceptance tests. +and the cloud are too high. This may lead to random failures in acceptance tests. ### Debugging @@ -671,8 +677,8 @@ PhpBrowser will store the HTML code and WebDriver will save a screenshot of the Additional debugging features by Codeception: -* [Interactive Pause](https://codeception.com/docs/02-GettingStarted#Interactive-Pause) is a REPL that allows to type and check commands for instant feedback. -* [Recorder Extension](https://codeception.com/addons#CodeceptionExtensionRecorder) allows to record tests step-by-steps and show them in slideshow +* [Interactive Pause](https://codeception.com/docs/Debugging#Pause) is a REPL that allows to type and check commands for instant feedback. +* [Recorder Extension](https://codeception.com/extensions#Recorder) allows to record tests step-by-step and show them in slideshow ### Common Cases @@ -751,16 +757,16 @@ Note that session restoration only works for `WebDriver` modules By default, WebDriver module is configured to automatically start browser before the test and stop afterward. However, this can be switched off with `start: false` module configuration. -To start a browser you will need to write corresponding methods in Acceptance [Helper](https://codeception.com/docs/06-ModulesAndHelpers#Helpers). +To start a browser you will need to write corresponding methods in Acceptance [Helper](https://codeception.com/docs/ModulesAndHelpers#Helpers). WebDriver module provides advanced methods for the browser session, however, they can only be used from Helpers. * [_initializeSession](https://codeception.com/docs/modules/WebDriver#_initializeSession) - starts a new browser session * [_closeSession](https://codeception.com/docs/modules/WebDriver#_closeSession) - stops the browser session * [_restart](https://codeception.com/docs/modules/WebDriver#_restart) - updates configuration and restarts browser -* [_capabilities](https://codeception.com/docs/modules/WebDriver#_capabilities) - set [desired capabilities](https://github.com/SeleniumHQ/selenium/wiki/DesiredCapabilities) programmatically. +* [_capabilities](https://codeception.com/docs/modules/WebDriver#_capabilities) - set [desired capabilities](https://www.selenium.dev/documentation/webdriver/drivers/options/) programmatically. -Those methods can be used to create custom commands like `$I->startBrowser()` or used in [before/after](https://codeception.com/docs/06-ModulesAndHelpers#Hooks) hooks. +Those methods can be used to create custom commands like `$I->startBrowser()` or used in [before/after](https://codeception.com/docs/ModulesAndHelpers#Hooks) hooks. ## Conclusion diff --git a/docs/AdvancedUsage.md b/docs/AdvancedUsage.md index 27f774be1..c1bf16fde 100644 --- a/docs/AdvancedUsage.md +++ b/docs/AdvancedUsage.md @@ -12,9 +12,9 @@ and keep your project better organized. ## Cest Classes Cest is a common test format for Codeception, it is "Test" with the first C letter in it. -It is scenario-driven format so all tests written in it are executed step by step. -Unless you need direct access to application code inside a test, Cest format is recommended. -As it provides more readable code for functional, api, and acceptance tests. +It is a scenario-driven format, so all tests written in it are executed step by step. +Unless you need direct access to application code inside a test, Cest format is recommended, +as it provides more readable code for functional, API, and acceptance tests. A new Cest class can be created via `g:cest` command: @@ -103,6 +103,7 @@ namespace Tests\Acceptance; use Codeception\Attribute\Skip; use Codeception\Scenario; +use Tests\Support\AcceptanceTester; class UserCest { @@ -319,6 +320,7 @@ namespace Tests\Acceptance; use Codeception\Attribute\DataProvider; use Codeception\Example; +use Tests\Support\AcceptanceTester; class PageCest { @@ -401,6 +403,7 @@ If that test fails, the current test will be skipped. You should pass the method namespace Tests\Acceptance; use Codeception\Attribute\Depends; +use Tests\Support\AcceptanceTester; class ModeratorCest { @@ -507,7 +510,7 @@ 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: ``` -php vendor/bin/codecept run Acceptance --env dev,firefox --env dev,chrome --env dev,firefox +php vendor/bin/codecept run Acceptance --env dev,firefox --env dev,chrome ``` The configuration is merged in the order given. @@ -523,6 +526,7 @@ The desired environments can be specified with the `Env` attribute: namespace Tests\Acceptance; use Codeception\Attribute\Env; +use Tests\Support\AcceptanceTester; class UserCest { @@ -531,7 +535,7 @@ class UserCest */ #[Env('firefox')] #[Env('chrome')] - public function webkitOnlyTest(AcceptanceTester $I) + public function firefoxAndChromeOnlyTest(AcceptanceTester $I) { // I do something } @@ -554,7 +558,7 @@ It is possible to combine environments. For instance, if a test should be execut Test marked with this attribute will be executed only if both environments are set: -```php +```bash php vendor/bin/codecept run --env chrome,staging ``` @@ -615,7 +619,7 @@ settings: Alternatively, you may run tests in the shuffle without changing the config: -```yaml +```bash codecept run -o "settings: shuffle: true" ``` @@ -630,7 +634,7 @@ Codeception PHP Testing Framework v5.3.7 https://stand-with-ukraine.pp.ua Pass the copied seed into `--seed` option: -```yaml +```bash codecept run --seed 1872290562 ``` diff --git a/docs/BDD.md b/docs/BDD.md index c6e5e8d84..58bbe393d 100644 --- a/docs/BDD.md +++ b/docs/BDD.md @@ -15,7 +15,7 @@ BDD was introduced by [Dan North](https://dannorth.net/introducing-bdd/). He des > outside-in, pull-based, multiple-stakeholder, multiple-scale, high-automation, agile methodology. It describes a cycle of interactions with well-defined outputs, resulting in the delivery of working, tested software that matters. -BDD has its own evolution from the days it was born, started by replacing "test" to "should" in unit tests, and moving towards powerful tools like Cucumber and Behat, which made user stories (human readable text) to be executed as an acceptance test. +BDD has its own evolution from the days it was born, started by replacing "test" with "should" in unit tests, and moving towards powerful tools like Cucumber and Behat, which made it possible to execute user stories (human-readable text) as acceptance tests. The idea of story BDD can be narrowed to: @@ -34,7 +34,7 @@ With this procedure we also ensure that everyone in a team knows what has been d ### Ubiquitous Language -The ubiquitous language is always referred as *common* language. That is it's main benefit. It is not a couple of our business specification's words, and not a couple of developer's technical terms. It is a common words and terms that can be understood by people for whom we are building the software and should be understood by developers. Establishing correct communication between this two groups people is vital for building successful project that will fit the domain and fulfill all business needs. +The ubiquitous language is always referred to as *common* language. That is its main benefit. It is not a couple of our business specification's words, and not a couple of developer's technical terms. It is the common words and terms that can be understood by people for whom we are building the software and should be understood by developers. Establishing correct communication between these two groups of people is vital for building a successful project that will fit the domain and fulfill all business needs. Each feature of a product should be born from a talk between @@ -44,7 +44,7 @@ Each feature of a product should be born from a talk between which are known in BDD as "three amigos". -Such talks should produce written stories. There should be an actor that doing some things, the feature that should be fulfilled within the story and the result achieved. +Such talks should produce written stories. There should be an actor that does some things, the feature that should be fulfilled within the story and the result achieved. We can try to write such simple story: @@ -54,7 +54,7 @@ I put first product with $600 price to my cart And then another one with $1000 price When I go to checkout process I should see that total number of products I want to buy is 2 -Andmy order amount is $1600 +And my order amount is $1600 ``` As we can see this simple story highlights core concepts that are called *contracts*. We should fulfill those contracts to model software correctly. But how we can verify that those contracts are being satisfied? [Cucumber](https://cucumber.io) introduced a special language for such stories called **Gherkin**. Same story transformed to Gherkin will look like this: @@ -189,7 +189,7 @@ Our next step will be to define those steps and transforming feature-file into v ### Step Definitions -To match steps from a feature file to PHP code we use attribute which are added to class methods. +To match steps from a feature file to PHP code we use attributes which are added to class methods. By default Codeception expects steps in methods marked with `Given`, `When`, `Then` attributes. Attributes can be loaded from `Codeception\Attribute` namespace: @@ -240,7 +240,7 @@ Steps are defined in Context files. Default context is an actor class, i.e. for To list all defined steps run `gherkin:steps` command: ```bash -php vendor/bin/codecept gherkin:steps +php vendor/bin/codecept gherkin:steps Acceptance ``` ## Testing Behavior @@ -294,7 +294,7 @@ class AcceptanceTester extends \Codeception\Actor Please note that `:num1` placeholder can be used for strings and numbers (may contain currency sign). In current case `:num1` matches `$600` and `$num1` is assigned to be 600. If you need to receive exact string, wrap the value into quotes: `"600$"` -By default they throw Incomplete exceptions to ensure test with missing steps won't be accidentally marked as successful. We will need to implement those steps. As we are in acceptance suite we are probably using [PHPBrowser](https://codeception.com/docs/modules/PhpBrowser) or [WebDriver](https://codeception.com/docs/modules/WebDriver) modules. This means that we can use their methods inside Tester file, as we do with writing tests using `$I->`. You can use `amOnPage`, `click`, `see` methods inside a step definitions, so each Gherkin scenario step to be extended with basic Codeception steps. Let's show how it can be implemented in our case: +By default they throw Incomplete exceptions to ensure test with missing steps won't be accidentally marked as successful. We will need to implement those steps. As we are in acceptance suite we are probably using [PhpBrowser](https://codeception.com/docs/modules/PhpBrowser) or [WebDriver](https://codeception.com/docs/modules/WebDriver) modules. This means that we can use their methods inside Tester file, as we do with writing tests using `$I->`. You can use `amOnPage`, `click`, `see` methods inside a step definitions, so each Gherkin scenario step to be extended with basic Codeception steps. Let's show how it can be implemented in our case: ```php note: we can't have multiple `c3_url` on same host difference only by port. Please, use alias of domain +> note: we can't have multiple `c3_url` on the same host differing only by port. Please, use alias of domain (i.e. `frontend.test:8000`,`backend.test:8080`) instead. -After the `c3.php` file is included in application you can start gather coverage. +After the `c3.php` file is included in application you can start gathering coverage. In case you execute your application locally there is nothing to be changed in config. All codecoverage reports will be collected as usual and merged afterwards. Think of it: Codeception runs remote coverage in the same way as local. @@ -142,7 +142,7 @@ It's possible to override the cookie domain set by Codeception during code cover have several subdomains that your acceptance tests are visiting, e.g. `mysite.com` and `admin.mysite.com`. By default, Codeception will run code coverage only for the domain set in the url of the `WebDriver/url` (or `c3_url` if defined), thus leaving out other subdomains from code coverage. To avoid that and to include all relevant subdomains in code -covereage, it's advised to set `.mysite.com` as the cookie domain option: +coverage, it's advised to set `.mysite.com` as the cookie domain option: ```yaml @@ -190,7 +190,7 @@ coverage: ### Remote Context Options HTML report generation can at times take a little more time than the default 30 second timeout. Or maybe you want to alter SSL settings (verify_peer, for example) -To alter the way c3 sends it's service requests to your webserver (be it a local or a remote one), you can use the `remote_context_options` key in `coverage` settings. +To alter the way c3 sends its service requests to your webserver (be it a local or a remote one), you can use the `remote_context_options` key in `coverage` settings. ```yaml diff --git a/docs/ContinuousIntegration.md b/docs/ContinuousIntegration.md index a5eea00a0..86a8a3f8d 100644 --- a/docs/ContinuousIntegration.md +++ b/docs/ContinuousIntegration.md @@ -7,7 +7,7 @@ title: Continuous Integration - Codeception Docs # Continuous Integration -Once you get testing suite up and running you are interested in running your tests regularly. If you ensure that tests are running on every code change or at least once a day you can be sure that no regression is introduced. This allows to keep you system stable. But developers are not so passionate about running all tests manually, they also can forget to execute tests before pushing code to production... The solution is simple, test execution should be automated. Instead of running them locally it is better to have dedicated server responsible for running tests for a team. This way we can ensure that everyone's tests executed, which commit made a regression in codebase, and that we can deploy only once tests pass. +Once you get testing suite up and running you are interested in running your tests regularly. If you ensure that tests are running on every code change or at least once a day you can be sure that no regression is introduced. This allows to keep your system stable. But developers are not so passionate about running all tests manually, they also can forget to execute tests before pushing code to production... The solution is simple, test execution should be automated. Instead of running them locally it is better to have dedicated server responsible for running tests for a team. This way we can ensure that everyone's tests executed, which commit made a regression in codebase, and that we can deploy only once tests pass. There are many Continuous Integration Servers out there. We will try to list basic steps to setup Codeception tests with them. If your CI system is not mentioned, you can get the idea by analogy. Please also help us to extend this guide by adding instructions for different CIs. @@ -15,7 +15,7 @@ There are many Continuous Integration Servers out there. We will try to list bas ![Jenkins](https://codeception.com/images/jenkins/Jenk1.png) -[Jenkins](https://jenkins-ci.org/) is one of the most popular open-source solution on market. It is easy to setup and is easy to customize by applying various plugins. +[Jenkins](https://jenkins-ci.org/) is one of the most popular open-source solutions on the market. It is easy to setup and is easy to customize by applying various plugins. ![Create new job in Jenkins](https://codeception.com/images/jenkins/Jenk2.png) @@ -65,7 +65,7 @@ Now we should specify path to PHPUnit style XML reports. In case of standard Cod ![Jenkins Result Trend](https://codeception.com/images/jenkins/Jenk8.png) -Now for all builds we will see results trend graph that shows us percentage of passing and failing tests. We also will see a **Latest Test Result** link which will lead to to the page where all executed tests and their stats listed in a table. +Now for all builds we will see results trend graph that shows us percentage of passing and failing tests. We also will see a **Latest Test Result** link which will lead to the page where all executed tests and their stats listed in a table. ### HTML Reports @@ -184,7 +184,7 @@ test: expire_in: 1 week paths: - tests/_output - # make the report available in Gitlab UI. see https://docs.gitlab.com/ee/ci/unit_test_reports.html + # make the report available in Gitlab UI. see https://docs.gitlab.com/ci/testing/unit_test_reports/ reports: junit: tests/_output/report.xml ``` diff --git a/docs/Customization.md b/docs/Customization.md index 9e0d47981..684154cbb 100644 --- a/docs/Customization.md +++ b/docs/Customization.md @@ -73,7 +73,7 @@ bootstrap: bootstrap.php Bootstrap script can be executed with `--bootstrap` option for `codecept run` command: -```php +```bash php vendor/bin/codecept run --bootstrap bootstrap.php ``` @@ -93,7 +93,7 @@ but can be useful if you are an experienced developer and you want to hook into By default, one `RunFailed` Extension is already enabled in your global `codeception.yml`. It allows you to rerun failed tests by using the `-g failed` option: -```php +```bash php vendor/bin/codecept run -g failed ``` @@ -119,22 +119,22 @@ All listed events are available as constants in `Codeception\Events` class. | Event | When? | Triggered by |:--------------------:| --------------------------------------- | --------------------------: -| `suite.before` | Before suite is executed | [Suite, Settings](https://github.com/Codeception/Codeception/blob/5.0/src/Codeception/Event/SuiteEvent.php) -| `test.start` | Before test is executed | [Test](https://github.com/Codeception/Codeception/blob/5.0/src/Codeception/Event/TestEvent.php) -| `test.before` | At the very beginning of test execution | [Codeception Test](https://github.com/Codeception/Codeception/blob/5.0/src/Codeception/Event/TestEvent.php) -| `step.before` | Before step | [Step](https://github.com/Codeception/Codeception/blob/5.0/src/Codeception/Event/StepEvent.php) -| `step.after` | After step | [Step](https://github.com/Codeception/Codeception/blob/5.0/src/Codeception/Event/StepEvent.php) -| `step.fail` | After failed step | [Step](https://github.com/Codeception/Codeception/blob/5.0/src/Codeception/Event/StepEvent.php) -| `test.fail` | After failed test | [Test, Fail](https://github.com/Codeception/Codeception/blob/5.0/src/Codeception/Event/FailEvent.php) -| `test.error` | After test ended with error | [Test, Fail](https://github.com/Codeception/Codeception/blob/5.0/src/Codeception/Event/FailEvent.php) -| `test.incomplete` | After executing incomplete test | [Test, Fail](https://github.com/Codeception/Codeception/blob/5.0/src/Codeception/Event/FailEvent.php) -| `test.skipped` | After executing skipped test | [Test, Fail](https://github.com/Codeception/Codeception/blob/5.0/src/Codeception/Event/FailEvent.php) -| `test.success` | After executing successful test | [Test](https://github.com/Codeception/Codeception/blob/5.0/src/Codeception/Event/TestEvent.php) -| `test.after` | At the end of test execution | [Codeception Test](https://github.com/Codeception/Codeception/blob/5.0/src/Codeception/Event/TestEvent.php) -| `test.end` | After test execution | [Test](https://github.com/Codeception/Codeception/blob/5.0/src/Codeception/Event/TestEvent.php) -| `suite.after` | After suite was executed | [Suite, Result, Settings](https://github.com/Codeception/Codeception/blob/5.0/src/Codeception/Event/SuiteEvent.php) -| `test.fail.print` | When test fails are printed | [Test, Fail](https://github.com/Codeception/Codeception/blob/5.0/src/Codeception/Event/FailEvent.php) -| `result.print.after` | After result was printed | [Result, Printer](https://github.com/Codeception/Codeception/blob/5.0/src/Codeception/Event/PrintResultEvent.php) +| `suite.before` | Before suite is executed | [Suite, Settings](https://github.com/Codeception/Codeception/blob/main/src/Codeception/Event/SuiteEvent.php) +| `test.start` | Before test is executed | [Test](https://github.com/Codeception/Codeception/blob/main/src/Codeception/Event/TestEvent.php) +| `test.before` | At the very beginning of test execution | [Codeception Test](https://github.com/Codeception/Codeception/blob/main/src/Codeception/Event/TestEvent.php) +| `step.before` | Before step | [Step](https://github.com/Codeception/Codeception/blob/main/src/Codeception/Event/StepEvent.php) +| `step.after` | After step | [Step](https://github.com/Codeception/Codeception/blob/main/src/Codeception/Event/StepEvent.php) +| `step.fail` | After failed step | [Step](https://github.com/Codeception/Codeception/blob/main/src/Codeception/Event/StepEvent.php) +| `test.fail` | After failed test | [Test, Fail](https://github.com/Codeception/Codeception/blob/main/src/Codeception/Event/FailEvent.php) +| `test.error` | After test ended with error | [Test, Fail](https://github.com/Codeception/Codeception/blob/main/src/Codeception/Event/FailEvent.php) +| `test.incomplete` | After executing incomplete test | [Test, Fail](https://github.com/Codeception/Codeception/blob/main/src/Codeception/Event/FailEvent.php) +| `test.skipped` | After executing skipped test | [Test, Fail](https://github.com/Codeception/Codeception/blob/main/src/Codeception/Event/FailEvent.php) +| `test.success` | After executing successful test | [Test](https://github.com/Codeception/Codeception/blob/main/src/Codeception/Event/TestEvent.php) +| `test.after` | At the end of test execution | [Codeception Test](https://github.com/Codeception/Codeception/blob/main/src/Codeception/Event/TestEvent.php) +| `test.end` | After test execution | [Test](https://github.com/Codeception/Codeception/blob/main/src/Codeception/Event/TestEvent.php) +| `suite.after` | After suite was executed | [Suite, Result, Settings](https://github.com/Codeception/Codeception/blob/main/src/Codeception/Event/SuiteEvent.php) +| `test.fail.print` | When test fails are printed | [Test, Fail](https://github.com/Codeception/Codeception/blob/main/src/Codeception/Event/FailEvent.php) +| `result.print.after` | After result was printed | [Result, Printer](https://github.com/Codeception/Codeception/blob/main/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 the suite around each test, while the before and after events are triggered @@ -142,7 +142,7 @@ from inside the test and are also dispatched per group (see [Group Objects](#Gro 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). +[Codeception internal event listeners](https://github.com/Codeception/Codeception/tree/main/src/Codeception/Subscriber). The extension class itself is inherited from `Codeception\Extension`: @@ -251,10 +251,10 @@ extensions: ``` -If you want to activate the Command globally, because you are using more then one `codeception.yml` file, +If you want to activate the Command globally, because you are using more than one `codeception.yml` file, you have to register your command in the `codeception.dist.yml` in the root folder of your project. -Please see the [complete example](https://github.com/Codeception/Codeception/blob/5.0/tests/data/register_command/examples/MyCustomCommand.php) +Please see the [complete example](https://github.com/Codeception/Codeception/blob/main/tests/data/register_command/examples/MyCustomCommand.php) ## Group Objects @@ -337,7 +337,7 @@ Actor classes include generated steps taken from corresponding modules and helpe You can introduce wrappers for those steps by using step decorators. Step decorators are used to implement conditional assertions. -When enabled, conditional assertions take all method prefixed by `see` or `dontSee` and introduce new steps prefixed with `canSee` and `cantSee`. +When enabled, conditional assertions take all methods prefixed by `see` or `dontSee` and introduce new steps prefixed with `canSee` and `cantSee`. Contrary to standard assertions those assertions won't stop test on failure. This is done by wrapping action into try/catch blocks. List of available step decorators: @@ -381,7 +381,7 @@ php vendor/bin/codecept bootstrap ~/projects/drupal/ ``` Also, the `-c` option allows you to specify another config file to be used. -Thus, you can have several `codeception.yml` files for your test suite (e.g. to to specify different environments +Thus, you can have several `codeception.yml` files for your test suite (e.g. to specify different environments and settings). Just pass the `.yml` filename as the `-c` parameter to execute tests with specific config settings. ### Group Files @@ -403,7 +403,7 @@ A list of tests for the group can be passed from a Group file. It should be defi ``` tests/Unit/DbTest.php -tests/Unit/UserTest.php:creat +tests/Unit/UserTest.php:create tests/Unit/UserTest.php:update ``` diff --git a/docs/Data.md b/docs/Data.md index 886639ccf..558fa5fca 100644 --- a/docs/Data.md +++ b/docs/Data.md @@ -65,7 +65,7 @@ modules: user: 'root' password: '' cleanup: true # run populator before each test - populate: true # run populator before all test + populate: true # run populator before all tests populator: 'mysql -u $user $dbname < tests/Support/Data/dump.sql' ``` @@ -236,7 +236,7 @@ Once configured, it can create records with ease: ```php // creates a new user -$user_id = $I->have(\App\Model\User::class); +$user = $I->have(\App\Model\User::class); // creates 3 posts $I->haveMultiple(\App\Model\Post::class, 3); ``` @@ -271,13 +271,13 @@ Read the [full reference](https://codeception.com/docs/modules/DataFactory) to l What if you deal with data which you don't own? For instance, the page look depends on number of categories in database, and categories are set by admin user. How would you test that the page is still valid? -There is a way to get it tested as well. Codeception allows you take a snapshot of a data on first run and compare with on next executions. +There is a way to get it tested as well. Codeception allows you to take a snapshot of data on the first run and compare it on subsequent executions. This principle is so general that it can work for testing APIs, items on a web page, etc. Let's check that list of categories on a page is the same it was before. Create a snapshot class: -```php +```bash php vendor/bin/codecept g:snapshot Categories ``` @@ -313,7 +313,7 @@ Inside a test you can inject the snapshot class and call `assert` method on it: public function testCategoriesAreTheSame(AcceptanceTester $I, \Tests\Support\Snapshot\Categories $snapshot) { $I->amOnPage('/categories'); - // if previously saved array of users does not match current set, test will fail + // if previously saved array of categories does not match current set, test will fail // to update data in snapshot run test with --debug flag $snapshot->assert(); } @@ -345,7 +345,7 @@ If ever needed, the diff output can also be omitted by calling `shouldShowDiffOn ### Change Storage Format -By default, all snapshot files are stored in json format, so if you have to work with different formats, neither the diff output or the snapshot file data will be helpful. +By default, all snapshot files are stored in json format, so if you have to work with different formats, neither the diff output nor the snapshot file data will be helpful. To fix this, you can call the snapshot method `shouldSaveAsJson(false)` and set the file extension by calling `setSnapshotFileExtension()`: ```php diff --git a/docs/Debugging.md b/docs/Debugging.md index f81445490..2c2ccb706 100644 --- a/docs/Debugging.md +++ b/docs/Debugging.md @@ -15,7 +15,7 @@ By looking into the following debugging practices you will learn how to get all Codeception saves the list of failed tests. To re-run failed test run tests from `failed` group: -```php +```bash php vendor/bin/codecept run -g failed ``` @@ -30,7 +30,7 @@ Think of it as `var_dump` but for testing: codecept_debug($user); ``` -Unlinke var_dump, the output will be printed to screen only if tests are executed with `--debug` flag. +Unlike var_dump, the output will be printed to screen only if tests are executed with `--debug` flag. ``` php vendor/bin/codecept run --debug @@ -41,7 +41,7 @@ So it is safe to keep `codecept_debug` inside a test, it won't affect the code r `codecept_debug` can be used in any place of your tests, but it is prohibited to use it in application code. This function is loaded only by Codeception, so the application may be broken trying to call this line. -Inside a [Helper](/docs/06-ModulesAndHelpers#Helpers) you can use analogs of this function to provide a debug output for a complex action. +Inside a [Helper](/docs/ModulesAndHelpers#Helpers) you can use analogs of this function to provide a debug output for a complex action. ```php @@ -66,7 +66,7 @@ $I->amOnPage('/'); $I->pause(); ``` -Interactive pause is launched only when `--debug ` option is enabled: +Interactive pause is launched only when `--debug` option is enabled: ``` php vendor/bin/codecept run --debug @@ -75,7 +75,7 @@ php vendor/bin/codecept run --debug To launch interactive pause in a context when the `$I` object is not available, use `codecept_pause` function instead. To inspect local variables pass them into interactive shell using an array: ```php -$I->pause(['user' => $user]) +$I->pause(['user' => $user]); // or codecept_pause(['user' => $user]); ``` diff --git a/docs/FunctionalTests.md b/docs/FunctionalTests.md index 5783aeb8a..7a3fca8d8 100644 --- a/docs/FunctionalTests.md +++ b/docs/FunctionalTests.md @@ -151,7 +151,7 @@ modules: ## Writing Functional Tests -Functional tests are written in the same manner as [Acceptance Tests](https://codeception.com/docs/03-AcceptanceTests) +Functional tests are written in the same manner as [Acceptance Tests](https://codeception.com/docs/AcceptanceTests) with the `PhpBrowser` module enabled. All framework modules and the `PhpBrowser` module share the same methods and the same engine. @@ -225,7 +225,7 @@ The error reporting level can be set in the suite configuration file: ```yaml actor: FunctionalTester -... +# ... error_level: E_ALL & ~E_DEPRECATED ``` diff --git a/docs/GettingStarted.md b/docs/GettingStarted.md index 79187a05e..748a7bb6f 100644 --- a/docs/GettingStarted.md +++ b/docs/GettingStarted.md @@ -15,7 +15,7 @@ They are well described in the [Introduction](https://codeception.com/docs/Intro Codeception follows simple naming rules to make it easy to remember (as well as easy to understand) its method names. -* **Actions** start with a plain english verb, like "click" or "fill". Examples: +* **Actions** start with a plain English verb, like "click" or "fill". Examples: ```php $I->click('Login'); diff --git a/docs/Introduction.md b/docs/Introduction.md index 01a4ef8c8..dfe077752 100644 --- a/docs/Introduction.md +++ b/docs/Introduction.md @@ -22,7 +22,7 @@ To test the behavior of your application as a whole, you should also write funct | | Unit Tests | Functional Tests | Acceptance Tests | --- | --- | --- | --- | -| Scope of the test | Single PHP class | PHP Framework (Routing, Database, etc.) | Page in browser (Chrome, Firefox, or [PhpBrowser](https://codeception.com/docs/03-AcceptanceTests#PhpBrowser)) | +| Scope of the test | Single PHP class | PHP Framework (Routing, Database, etc.) | Page in browser (Chrome, Firefox, or [PhpBrowser](https://codeception.com/docs/AcceptanceTests#PhpBrowser)) | | Testing computer needs access to project's PHP files | Yes | Yes | No | | Webserver required | No | No | Yes | | JavaScript | No | No | Yes | @@ -96,7 +96,7 @@ Testing pieces of code before coupling them together is highly important as well you can be sure that some deeply hidden feature still works, even if it was not covered by functional or acceptance tests. This also shows care in producing stable and testable code. -Codeception is created on top of [PHPUnit](https://www.phpunit.de/). If you have experience writing unit tests with PHPUnit +Codeception is created on top of [PHPUnit](https://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, additionally, Codeception provides some well-built tools to make your unit tests simpler and cleaner. diff --git a/docs/ModulesAndHelpers.md b/docs/ModulesAndHelpers.md index 7f33b8c19..1d994f476 100644 --- a/docs/ModulesAndHelpers.md +++ b/docs/ModulesAndHelpers.md @@ -53,7 +53,7 @@ and not on reinventing the wheel. Each module provides methods for testing its o by combining modules you can get a powerful setup to test an application at all levels. There is the `WebDriver` module for acceptance testing, modules for all popular PHP frameworks, -`PHPBrowser` to emulate browser execution, `REST` for testing APIs, and more. +`PhpBrowser` to emulate browser execution, `REST` for testing APIs, and more. Modules are considered to be the most valuable part of Codeception. They are constantly improving to provide the best testing experience, and be flexible to satisfy everyone's needs. @@ -74,7 +74,7 @@ This way if you try to use two modules sharing the same conflicted interface you To avoid confusion, **Framework modules, PhpBrowser, and WebDriver** can't be used together. For instance, the `amOnPage` method exists in all those modules, and you should not try to guess which module will actually execute it. -If you are doing acceptance testing, set up either WebDriver or PHPBrowser but do not set both up at the same time. +If you are doing acceptance testing, set up either WebDriver or PhpBrowser but do not set both up at the same time. If you are doing functional testing, enable only one of the framework modules. In case you need to use a module which depends on a conflicted one, specify it as a dependent module in the configuration. @@ -463,7 +463,7 @@ modules: ``` -Parameters can set in JSON format. So objects, arrays, booleans and strings can also be passed into config. +Parameters can be set in JSON format. So objects, arrays, booleans and strings can also be passed into config. ```yaml modules: @@ -473,7 +473,7 @@ modules: books: "%BOOKS_ARRAY%" ``` -In this case `USER_ARRAY` and `BOOKS_ARRAY` are JSON-fromatted arrays. Codeception turns them into array while parsing configuration. +In this case `USERS_ARRAY` and `BOOKS_ARRAY` are JSON-formatted arrays. Codeception turns them into array while parsing configuration. ### Runtime Configuration diff --git a/docs/ParallelExecution.md b/docs/ParallelExecution.md index 2d1b07358..8b0f0f37a 100644 --- a/docs/ParallelExecution.md +++ b/docs/ParallelExecution.md @@ -9,12 +9,12 @@ title: Parallel Execution - Codeception Docs When execution time of your tests is longer than a coffee break, it is a good reason to think about making your tests faster. If you have already tried to run them on SSD drive, and the execution time still upsets you, it might be a good idea to run your tests in parallel. However, PHP runs in a single-process and you can't parallelize tests natively similarly to how this works in Java or in NodeJS. -Depending on the project size and requirements you can choose how the best to implement parallel testing for your case. +Depending on the project size and requirements you can choose how best to implement parallel testing for your case. In this guide we will overview possible options. ## Sharding -Minimal setup can be implemented by executing several independent CI jobs and running. +Minimal setup can be implemented by executing several independent CI jobs, each running a part of the tests. Sharding in Codeception allows to combine stages 1 and 2 so tests could be split by groups on the fly. In this case a pipeline could be simplified to one stage with several jobs. @@ -67,7 +67,7 @@ While sharding provides a simplified setup for testing the complete pipeline sch * On the third stage the results from previous jobs must be collected or aggregated. -To get more control on how the jobs are split excuted and results aggregated you can use a task runner. +To get more control on how the jobs are split, executed and results aggregated you can use a task runner. Codeception provides a toolset for [Robo task runner](https://robo.li) called [robo-paracept](https://github.com/Codeception/robo-paracept) for splitting tests into groups and merging resulting JUnit XML reports. @@ -78,9 +78,9 @@ To sum up, we need to install: ## Using Robo and Robo-paracept -Execute this command in an empty folder to install Robo and Robo-paracept : +Execute this command in your project root to install Robo and Robo-paracept: -```php +```bash composer require codeception/robo-paracept --dev ``` @@ -132,7 +132,7 @@ class Robofile extends \Robo\Tasks } ``` -When running `robo` you should see all 3 that these methods availble as CLI commands: +When running `robo` you should see all 3 of these methods available as CLI commands: ``` parallel:split-tests @@ -142,7 +142,7 @@ parallel:merge-results #### Step 1: Split Tests -Codeception can organize tests into [groups](https://codeception.com/docs/AdvancedUsage#Groups). Starting from 2.0 it can load information about a group from a files. Sample text file with a list of file names can be treated as a dynamically configured group. Take a look into sample group file: +Codeception can organize tests into [groups](https://codeception.com/docs/AdvancedUsage#Groups). Starting from 2.0 it can load information about a group from a file. Sample text file with a list of file names can be treated as a dynamically configured group. Take a look into sample group file: ```bash @@ -214,9 +214,9 @@ php vendor/bin/codecept run Acceptance -g paracept_2 At this point you should decide if tests are executed on the same job or use multiple jobs for them. We recommend using multiple jobs, as in this case the burden of parallelization goes to CI server. This makes a lot of sense as a single machine has limited resources. If you split tests into CI jobs, you are limited only to the number of agents (build servers) that the CI can provide. For cloud-based services like GitHub Actions, GitLab CI, CircleCI, etc, this number is unlimited. -> Please refer to documentation of your CI platform to learn how to set up multiple jobs runnninng in parallel. Then proceed to merging of results. +> Please refer to documentation of your CI platform to learn how to set up multiple jobs running in parallel. Then proceed to merging of results. -In some situations you may want to keep tests running on the same machine and scale it up with more resourses. This makes sense if you have heavy application setup for each test run and setting it up for each machine can waste a lot of resources. +In some situations you may want to keep tests running on the same machine and scale it up with more resources. This makes sense if you have heavy application setup for each test run and setting it up for each machine can waste a lot of resources. To execute tests in multiple processes Robo has `ParallelExec` task to spawn background processes. @@ -266,16 +266,16 @@ php vendor/bin/robo parallel:merge-results `result_paracept.xml` file will be generated. It can be processed and analyzed. -If you prefer HTML reports, they can be generated in the same way: +If you prefer HTML reports, add `->html("result_paracept_$i.html")` to the Codecept task in `parallelRun` and merge them in the same way: ```php public function parallelMergeResults() { $merge = $this->taskMergeHtmlReports(); for ($i=1; $i<=5; $i++) { - $merge->from("tests/_output/result_$i.html"); + $merge->from("tests/_output/result_paracept_$i.html"); } - $merge->into("tests/_output/result.html")->run(); + $merge->into("tests/_output/result_paracept.html")->run(); } ``` diff --git a/docs/Reporting.md b/docs/Reporting.md index f715a0f33..ccbd0266d 100644 --- a/docs/Reporting.md +++ b/docs/Reporting.md @@ -7,11 +7,11 @@ title: Reporting - Codeception Docs ## Reporting -Clear reports gives a picture of the current state of the system. Which tests are passed, which tests are failed, and if failed what was the reason. Reports may vary on the level of detail and by the technical information collected. Codeception provides as built-in reporters and customizable API to create your own reporter. +Clear reports give a picture of the current state of the system. Which tests are passed, which tests are failed, and if failed what was the reason. Reports may vary on the level of detail and by the technical information collected. Codeception provides built-in reporters and a customizable API to create your own reporter. ## CLI -The standard reporter you already is CLI reporter. It is great for writing and debugging tests as well, as checking the results on CI. On failure, CLI reporter prints a list of all failed tests, if test includes some valuable data like last send requests for REST module, it will also be printed under 'artifacts' section of a test. +The standard reporter you already know is the CLI reporter. It is great for writing and debugging tests as well as checking the results on CI. On failure, CLI reporter prints a list of all failed tests, if test includes some valuable data like last sent requests for REST module, it will also be printed under 'artifacts' section of a test. ![](/images/codecept-cli.png) @@ -27,7 +27,7 @@ To see step-by-step execution in a runtime use `--steps` flag: php vendor/bin/codecept run --steps ``` -To get additional information which may be handful for debugging tests use `--debug` flag. +To get additional information which may be handy for debugging tests use `--debug` flag. This flag is your best friend for writing new tests. ``` @@ -67,7 +67,7 @@ Testomat.io reports are easy to set up and without storing artifacts on CI syste > 😻 Testomat.io is free for small teams, so you can use its reporting features with Codeception. -Testomat.io imports all tests into UI, so your managers, business analysts, and manual QAs can see all your unit, funcitonal, and acceptance tests listed in one place: +Testomat.io imports all tests into UI, so your managers, business analysts, and manual QAs can see all your unit, functional, and acceptance tests listed in one place: ![](/images/testomatio-import.png) @@ -98,7 +98,7 @@ Check an [Example Project](https://github.com/testomatio/examples/tree/master/co ## Recorder -By default Codeception saves the screenshot for a failed test for acceptance tests and show it in HTML report. However, can't be possible to understand cause of failure just by one screenshot. This is where Recorder extension is handy, it saves a screenshot after each step and shows them in a slideshow. +By default Codeception saves the screenshot for a failed test for acceptance tests and shows it in the HTML report. However, it may not be possible to understand the cause of failure just by one screenshot. This is where Recorder extension is handy, it saves a screenshot after each step and shows them in a slideshow. ![](https://codeception.com/images/recorder.gif) @@ -129,7 +129,7 @@ php vendor/bin/codecept run --xml ## Custom Reporter -Custom reporter can be built as an [Extension](https://codeception.com/docs/08-Customization#Extension). Extension can listen to all test events and log data from them. +Custom reporter can be built as an [Extension](https://codeception.com/docs/Customization#Extension). Extension can listen to all test events and log data from them. Look into the basic reporting extensions like [DotReporter](https://codeception.com/extensions#DotReporter) or [Logger](https://codeception.com/extensions#Logger) to learn how to build your own. Use them to change output or use them as an example to build your own reporter. They can be easily enabled with `--ext` option diff --git a/docs/ReusingTestCode.md b/docs/ReusingTestCode.md index 87b89090e..89e06eae3 100644 --- a/docs/ReusingTestCode.md +++ b/docs/ReusingTestCode.md @@ -79,14 +79,14 @@ The most important part is the `_generated\AcceptanceTesterActions` trait, which It knows which module executes which action and passes parameters into it. This trait was created by running `codecept build` and is regenerated each time module or configuration changes. -> Use actor classes to set common actions which can be used accross a suite. +> Use actor classes to set common actions which can be used across a suite. ## PageObjects For acceptance and functional testing, we will not only need to have common actions being reused across different tests, we should have buttons, links and form fields being reused as well. For those cases we need to implement -the [PageObject pattern](https://www.selenium.dev/documentation/en/guidelines_and_recommendations/page_object_models/), +the [PageObject pattern](https://www.selenium.dev/documentation/test_practices/encouraged/page_object_models/), which is widely used by test automation engineers. The PageObject pattern represents a web page as a class and the DOM elements on that page as its properties, and some basic interactions as its methods. PageObjects are very important when you are developing a flexible architecture of your acceptance or functional tests. @@ -192,9 +192,9 @@ Dependency Injection will be described in the next chapter. StepObjects are great if you need some common functionality for a group of tests. Let's say you are going to test an admin area of a site. You probably won't need the same actions from the admin area while testing the front end, so it's a good idea to move these admin-specific tests into their own class. -We call such a classes StepObjects. +We call such classes StepObjects. -Lets create an Admin StepObject with the generator: +Let's create an Admin StepObject with the generator: ``` php vendor/bin/codecept generate:stepobject Acceptance Admin diff --git a/docs/UnitTests.md b/docs/UnitTests.md index 1367b66a7..9e9a4b37c 100644 --- a/docs/UnitTests.md +++ b/docs/UnitTests.md @@ -51,7 +51,7 @@ class ExampleTest extends \Codeception\Test\Unit } // tests - public function testMe() + public function testSomeFeature() { } @@ -107,7 +107,7 @@ There are pretty many assertions you can use inside tests. The most common are: * `$this->assertNull()` * `$this->assertEmpty()` -Assertion methods come from PHPUnit. [See the complete reference at phpunit.de](https://docs.phpunit.de/en/main/assertions.html). +Assertion methods come from PHPUnit. [See the complete reference at phpunit.de](https://docs.phpunit.de/en/12.5/assertions.html). ### Fluent Assertions @@ -128,7 +128,7 @@ verify($user->getRate()) ->equals(7, 'first user rate is 7'); // array assertions -Verify::Array($user->getRoles()) +\Codeception\Verify\Verify::Array($user->getRoles()) ->contains('admin', 'first user is admin') ->notContains('banned', 'first user is not banned'); ``` @@ -136,13 +136,13 @@ Verify::Array($user->getRoles()) ### Test Doubles Codeception provides [Codeception\Stub library](https://github.com/Codeception/Stub) for building mocks and stubs for tests. -Under the hood it used PHPUnit's mock builder but with much simplified API. +Under the hood it uses PHPUnit's mock builder but with much simplified API. Alternatively, [Mockery](https://github.com/Codeception/MockeryModule) can be used inside Codeception. #### Stubs -Stubs can be created with a static methods of `Codeception\Stub`. +Stubs can be created with static methods of `Codeception\Stub`. ```php $user = \Codeception\Stub::make('User', ['getName' => 'john']); @@ -151,8 +151,8 @@ $name = $user->getName(); // 'john' [See complete reference](https://codeception.com/docs/reference/Mock) -To keep compatibility with PHPUnit its verification of expectations for Mocks, -it is recommended to use alternative API in unit tests (`Codeception\Test\Unit`): +To keep PHPUnit's verification of mock expectations working, +it is recommended to use the alternative API in unit tests (`Codeception\Test\Unit`): ```php // create a stub with find method replaced @@ -196,14 +196,14 @@ To declare expectations for mocks use `Codeception\Stub\Expected` class: ```php // create a mock where $user->getName() should never be called $user = $this->make('User', [ - 'getName' => Expected::never(), + 'getName' => \Codeception\Stub\Expected::never(), 'someMethod' => function() {} ]); $user->someMethod(); // create a mock where $user->getName() should be called at least once $user = $this->make('User', [ - 'getName' => Expected::atLeastOnce('Davert') + 'getName' => \Codeception\Stub\Expected::atLeastOnce('Davert') ] ); $user->getName(); @@ -215,8 +215,8 @@ $this->assertEquals('Davert', $userName); ## Integration Tests -Unlike unit tests integration tests doesn't require the code to be executed in isolation. -That allows us to use database and other components inside a tests. +Unlike unit tests, integration tests don't require the code to be executed in isolation. +That allows us to use database and other components inside tests. To improve the testing experience modules can be used as in functional testing. ### Using Modules @@ -235,7 +235,7 @@ modules: - Db ``` -To access UnitTester methods you can use the `UnitTester` property in a test. +To access UnitTester methods you can use the `$this->tester` property in a test. ### Testing Database @@ -363,7 +363,7 @@ The same can be done for all public properties of an enabled module. Accessible ### Scenario Driven Testing -[Cest format](https://codeception.com/docs/07-AdvancedUsage#Cest-Classes) can also be used for integration testing. +[Cest format](https://codeception.com/docs/AdvancedUsage#Cest-Classes) can also be used for integration testing. In some cases it makes tests cleaner as it simplifies module access by using common `$I->` syntax: ```php @@ -474,12 +474,14 @@ For instance, you can test singletons! ```php assertInstanceOf('MySingleton', $class); test::double('MySingleton', ['getInstance' => new DOMDocument]); - $this->assertInstanceOf('DOMDocument', $class); + $this->assertInstanceOf('DOMDocument', MySingleton::getInstance()); } ``` @@ -495,7 +497,7 @@ The error reporting level can be set in the suite configuration file: ```yaml actor: UnitTester -... +# ... error_level: E_ALL & ~E_DEPRECATED ``` diff --git a/docs/reference/Configuration.md b/docs/reference/Configuration.md index 253999f9c..ff5214ab6 100644 --- a/docs/reference/Configuration.md +++ b/docs/reference/Configuration.md @@ -88,18 +88,18 @@ settings: Possible settings: -* `backup_globals: true`: Controls whether PHPUnit attempts to backup global variables, see https://phpunit.de/manual/current/en/appendixes.annotations.html#appendixes.annotations.backupGlobals -* `be_strict_about_changes_to_global_state: false`: PHPUnit can be strict about tests that manipulate global state, see https://phpunit.de/manual/current/en/risky-tests.html#risky-tests.global-state-manipulation +* `backup_globals: true`: Controls whether PHPUnit attempts to backup global variables, see https://docs.phpunit.de/en/12.5/attributes.html#backupglobals +* `be_strict_about_changes_to_global_state: false`: PHPUnit can be strict about tests that manipulate global state, see https://docs.phpunit.de/en/12.5/risky-tests.html#global-state-manipulation * `colors: true`: Colorize console output. On older Windows consoles you may need [ANSICON](https://github.com/adoxa/ansicon) to display colors. * `convert_deprecations_to_exceptions: false` Converts E_DEPRECATED and E_USER_DEPRECATED events to exceptions. Introduced in Codeception 4.2.0 -* `disallow_test_output: false`: PHPUnit can be strict about output during tests, see https://phpunit.de/manual/current/en/risky-tests.html#risky-tests.output-during-test-execution +* `disallow_test_output: false`: PHPUnit can be strict about output during tests, see https://docs.phpunit.de/en/12.5/risky-tests.html#output-during-test-execution * `editor_url: 'atom://core/open/file?filename=%%file%%&line=%%line%%'`: In the console output, the test runner will replace all references to files with "clickable" URL's, allowing you to open the file directly in your IDE. Depending on your operating system, you may have to set up an appropriate uri handler. Syntax for some common editors (same as in [PHPStan](https://phpstan.org/user-guide/output-format#opening-file-in-an-editor)): * PhpStorm: `'phpstorm://open?file=%%file%%&line=%%line%%'` * Visual Studio Code: `'vscode://file/%%file%%:%%line%%'` * Atom: `'atom://core/open/file?filename=%%file%%&line=%%line%%'` * `error_level: E_ALL & ~E_DEPRECATED`: Set the error_reporting level. You can specify either a predefined constant or an integer value, see https://www.php.net/manual/en/function.error-reporting.php and https://www.php.net/manual/en/errorfunc.constants.php. `E_STRICT` is deprecated as of PHP 8.4: remove it from your `error_level` if you still reference it, to avoid a deprecation notice. * `memory_limit: 1024M`: Tests (especially functional) can take a lot of memory. We set a high limit for them by default. -* `report_useless_tests: false`: PHPUnit can be strict about tests that do not test anything, see https://phpunit.de/manual/current/en/risky-tests.html#risky-tests.useless-tests +* `report_useless_tests: false`: PHPUnit can be strict about tests that do not test anything, see https://docs.phpunit.de/en/12.5/risky-tests.html#useless-tests * `shuffle: false`: Set to `true` to randomize test order * `strict_xml: false`: Generate XML JUnit report using strict schema. Avoid putting additional report fields like steps or scenario names to it. Required for XML reports on Jenkins CI @@ -141,7 +141,7 @@ Per suite [Gherkin](https://codeception.com/docs/BDD#Configuration) settings. ### `groups` -[groups](https://codeception.com/docs/AdvancedUsage#Groups) with the list of tests of for corresponding group. +[groups](https://codeception.com/docs/AdvancedUsage#Groups) with the list of tests for the corresponding group. ### `formats` diff --git a/docs/reference/ShellAutocomplete.md b/docs/reference/ShellAutocomplete.md index e3900353f..8a77b40c8 100644 --- a/docs/reference/ShellAutocomplete.md +++ b/docs/reference/ShellAutocomplete.md @@ -19,8 +19,8 @@ By using the above code in your shell, Codeception will try to autocomplete the * Suites * Test paths -Usage of `-use-vendor-bin` is optional. This option will work for most Codeception projects, where Codeception is located in your `vendor/bin` folder. +Usage of `--use-vendor-bin` is optional. This option will work for most Codeception projects, where Codeception is located in your `vendor/bin` folder. But in case you are using a global Codeception installation for example, you wouldn't use this option. -Note that with the `-use-vendor-bin` option, your commands will be completed using the Codeception binary located in your project's root. +Note that with the `--use-vendor-bin` option, your commands will be completed using the Codeception binary located in your project's root. Without the option, it will use whatever Codeception binary you originally used to generate the completion script ('codecept location' in the above examples)