codeceptjs 3.5.12-beta.2 → 3.5.12-beta.3

package/docs/testcafe.md

@@ -1,174 +0,0 @@
----
-permalink: /testcafe
-title: Testing with TestCafe
----
-
-# Testing with TestCafe
-
-[TestCafe](https://devexpress.github.io/testcafe/) is another alternative engine for driving browsers. It is driven by unique technology which provides fast and simple cross browser testing for desktop and mobile browsers. Unlike WebDriver or Puppeteer, TestCafe doesn't control a browser at all. It is not a browser itself, like Cypress. **TestCafe core is a proxy server** that runs behind the scene, and transforms all HTML and JS to include code that is needed for test automation.
-
-![Testcafe](/img/testcafe.png)
-
-This is very smart idea. But to use TestCafe on daily basis you need to clearly understand its benefits and limitations:
-
-### Pros
-
-* **Fast**. Browser is controlled from inside a web page. This makes test run inside a browser as fast as your browser can render page with no extra network requests.
-* **Simple Cross-Browser Support.** Because TestCafe only launches browsers, it can **automate browser** on desktop or mobile. Unlike WebDriver, you don't need special version of browser and driver to prepare to run tests. Setup simplified. All you need is just a browser installed, and you are ready to go.
-* **Stable to Execution.** Because a test is executed inside a browser, the network latency effects are reduced. Unlike WebDriver you won't hit stale element exceptions, or element not interactable exceptions, as from within a web browser all DOM elements are accessible.
-
-## Cons
-
-* **Magic.** Browsers executed in TestCafe are not aware that they run in test mode. So at some edges automation control can be broken. It's also quite hard to debug possible issues, as you don't know how actually a web page is parsed to inject automation scripts.
-* **No Browser Control.** Because TestCafe do not control browser, you can't actually automate all users actions. For instance, TestCafe can't open new tabs or open a new browser window in incognito mode. There can be also some issues running tests on 3rd party servers or inside iframes.
-* **Simulated Events.** Events like `click` or `doubleClick` are simulated by JavaScript internally. Inside WebDriver or Puppeteer, where those events are dispatched by a browser, called native events. Native events are closer to real user experience. So in some cases simulated events wouldn't represent actual user experience, which can lead to false positive results. For instance, a button which can't be physically clicked by a user, would be clickable inside TestCafe.
-
-Anyway, TestCafe is a good option to start if you need cross browser testing. And here is the **reason to use TestCafe with CodeceptJS: if you hit an edge case or issue, you can easily switch your tests to WebDriver**. As all helpers in CodeceptJS share the same syntax.
-
-CodeceptJS is a rich testing frameworks which also provides features missing in original TestCafe:
-
-* [Cucumber integration](/bdd)
-* [Real Page Objects](/pageobjects)
-* [Data Management via API](/data)
-* and others
-
-## Writing Tests
-
-To start using TestCafe with CodeceptJS install both via NPM
-
-> If you don't have `package.json` in your project, create it with `npm init -y`.
-
-```
-npm i codeceptjs testcafe --save-dev
-```
-
-Then you need to initialize a project, selecting TestCafe when asked:
-
-```
-npx codeceptjs init
-```
-
-A first test should be created with `codeceptjs gt` command
-
-```
-npx codeceptjs gt
-```
-
-In the next example we will [TodoMVC application](https://todomvc.com/examples/angularjs/#/). So let's create a test which will fill in todo list:
-
-```js
-Feature('TodoMVC');
-
-Scenario('create todo item', ({ I }) => {
-  I.amOnPage('http://todomvc.com/examples/angularjs/#/');
-  I.fillField('.new-todo', todo)
-  I.pressKey('Enter');
-  I.seeNumberOfVisibleElements('.todo-list li', 1);
-  I.see('1 item left', '.todo-count');
-});
-```
-
-Same syntax is the same for all helpers in CodeceptJS so to learn more about available commands learn [CodeceptJS Basics](/basics).
-
-> [▶ Complete list of TestCafe actions](/helpers/TestCafe)
-
-## Page Objects
-
-Multiple tests can be refactored to share some logic and locators. It is recommended to use PageObjects for this. For instance, in example above, we could create special actions for creating todos and checking them. If we move such methods in a corresponding object a test would look even clearer:
-
-```js
-Scenario('Create a new todo item', async ({ I, TodosPage }) => {
-  I.say('Given I have an empty todo list')
-
-  I.say('When I create a todo "foo"')
-  TodosPage.enterTodo('foo')
-
-  I.say('Then I see the new todo on my list')
-  TodosPage.seeNumberOfTodos(1)
-
-  I.saveScreenshot('create-todo-item.png')
-})
-
-Scenario('Create multiple todo items', async ({ I, TodosPage }) => {
-  I.say('Given I have an empty todo list')
-
-  I.say('When I create todos "foo", "bar" and "baz"')
-  TodosPage.enterTodo('foo')
-  TodosPage.enterTodo('bar')
-  TodosPage.enterTodo('baz')
-
-  I.say('Then I have these 3 todos on my list')
-  TodosPage.seeNumberOfTodos(3)
-
-  I.saveScreenshot('create-multiple-todo-items.png')
-})
-```
-
-> ℹ [Source code of this example](https://github.com/hubidu/codeceptjs-testcafe-todomvc) is available on GitHub.
-
-A PageObject can be injected into a test by its name. Here is how TodosPage looks like:
-
-```js
-// inside todos_page.js
-const { I } = inject();
-
-module.exports = {
-    goto() {
-        I.amOnPage('http://todomvc.com/examples/angularjs/#/')
-    },
-
-    enterTodo(todo) {
-        I.fillField('.new-todo', todo)
-        I.pressKey('Enter')
-    },
-
-    seeNumberOfTodos(numberOfTodos) {
-        I.seeNumberOfVisibleElements('.todo-list li', numberOfTodos)
-    },
-}
-```
-
-> [▶ Read more about PageObjects in CodeceptJS](/pageobjects)
-
-
-## Accessing TestCafe API
-
-To get [testController](https://devexpress.github.io/testcafe/documentation/test-api/test-code-structure.html#test-controller))) inside a test use [`I.useTestCafeTo`](/helpers/TestCafe/#usetestcafeto) method with a callback.
-To keep test readable provide a description of a callback inside the first parameter.
-
-```js
-I.useTestCafeTo('do some things using native webdriverio api', async ({ t }) => {
-  await t.click() // use testcafe api here
-});
-```
-
-Because all TestCafe commands are asynchronous a callback function must be async.
-
-
-## Extending
-
-If you want to use TestCafe API inside your tests you can put them into actions of `I` object. To do so you can generate a new helper, access TestCafe helper, and get the test controller.
-
-Create a helper using `codecepjs gh` command.
-
-```
-npx codeceptjs gh
-```
-
-All methods of newly created class will be added to `I` object.
-
-```js
-const Helper = codeceptjs.helper;
-
-class MyTestCafe extends Helper {
-
-  slowlyFillField(field, text) {
-    // import test controller from TestCafe helper
-    const { t } = this.helpers.TestCafe;
-    // use TestCafe API here
-    return t.setTestSpeed(0.1)
-        .typeText(field, text);
-  }
-
-}
-```

package/docs/translation.md

@@ -1,247 +0,0 @@
----
-permalink: /translation
-title: Translation
----
-
-# Translation 
-
-*Unique feature of CodeceptJS: write tests in your language!*
-
-🇩🇪🇯🇵🇫🇷🇹🇼🇨🇳🇵🇱🇧🇷🇮🇹
-
-Test output and the way tests are written can be localized. This way scenarios can be written in almost native language using UTF support of JavaScript.
-
-If you have non-English team and you work on non-English project consider enabling translation
-by setting translation to [one of available languages](https://github.com/codeceptjs/CodeceptJS/blob/3.x/translations) or writing vocabulary for your language.
-
-## How it works
-
-CodceptJS provides a high-level domain specific language (DSL) for writing end-to-end tests. 
-As CodeceptJS API is designed to provide a minimal set of methods to write test cases of any kind of complexity.
-
-It is possible to add aliases for all CodeceptJS keywords and methods. So if all keywords and methods are translated to a specific language it is possible to write tests in that language. Sure, this is not perfect, as CSS/XPath locators as well as REST API speific words are used as is. However, writing tests in your native language may improve the team's understanding of the test behavior.
-
-You can enable translation if your team is not from English-speaking country developing non-English product.
-
-> ⚠️ It's important to note that default translations are far from being complete. So there are still lots of methods and keywords not translated to your language yet. We recommend to [extend a vocabulary](#extending-vocabulary) to add aliases for non-translated methods and submit a pull request with improvements to a [corresponding language file](https://github.com/codeceptjs/CodeceptJS/blob/3.x/translations).
-
-To enable translition create a new project with 
-
-```
-npx codeceptjs init
-```
-
-And select a language of your choice from a list:
-
-```
-? Do you want localization for tests? (See https://codecept.io/translation/)
-❯ English (no localization) 
-  de-DE 
-  it-IT 
-  fr-FR 
-  ja-JP 
-  pl-PL 
-  pt-BR 
-(Move up and down to reveal more choices)
-```
-> 💡 If you don't see your language in the list but still want to use localized tests, select 'English (no localization)' and create [custom translation](#custom-translation).
-
-
-## Languages
-
-### Portuguese 🇧🇷
-
-To write your tests in portuguese you can enable the portuguese translation in config file like:
-
-```js
-  translation: "pt-BR"
-```
-
-Now you can write test like this:
-
-```js
-Cenário('Efetuar login', ({ Eu }) => {
-    Eu.estouNaPagina('http://minhaAplicacao.com.br');
-    Eu.preenchoOCampo("login", "usuario@minhaAplicacao.com.br");
-    Eu.preenchoOCampo("senha", "123456");
-    Eu.clico("Entrar");
-    Eu.vejo("Seja bem vindo usuário!");
-});
-```
-
-### French 🇫🇷
-
-To write your tests in French you can enable the French translation by adding to config:
-
-```js
-  translation: "fr-FR"
-```
-
-Now you can write tests like this:
-
-```js
-Scenario('Se connecter sur GitHub', (Je) => {
-    Je.suisSurLaPage('https://github.com/login');
-    Je.remplisLeChamp("Username or email address", "jean-dupond");
-    Je.remplisLeChamp("Password", "*********");
-    Je.cliqueSur("Sign in");
-    Je.vois("Learn Git and GitHub without any code!");
-});
-```
-
-### Italian 🇮🇹
-
-Add to `codeceptjs.conf.js` or `codeceptjs.conf.ts` config file:
-
-```js
-  translation: "it-IT"
-```
-
-Now you can write test like this:
-
-```js
-Caratteristica('Effettuare il Login su GitHub', (io) => {
-    io.sono_sulla_pagina('https://github.com/login');
-    io.compilo_il_campo("Username or email address", "giuseppe-santoro");
-    io.compilo_il_campo("Password", "*********");
-    io.faccio_click_su("Sign in");
-    io.vedo("Learn Git and GitHub without any code!");
-});
-```
-
-### Polish 🇵🇱
-
-Add to `codeceptjs.conf.js` or `codeceptjs.conf.ts` config file:
-
-```js
-  translation: "pl-PL"
-```
-
-Now you can write test like this:
-
-```js
-Scenario('Zakładanie konta free trial na stronie głównej GetResponse', ({ Ja }) => {
-    Ja.jestem_na_stronie('https://getresponse.com');
-    Ja.wypełniam_pole("Email address", "sjakubowski@getresponse.com");
-    Ja.wypełniam_pole("Password", "digital-marketing-systems");
-    Ja.klikam('Sign up');
-    Ja.czekam(1);
-    Ja.widzę_w_adresie_url('/account_free_created.html');
-});
-```
-
-### Chinese 🇹🇼🇨🇳
-
-Add to `codeceptjs.conf.js` or `codeceptjs.conf.ts` config: file:
-
-```JS
-  translation: "zh-CN"
-```
-or
-```JS
-  translation: "zh-TW"
-```
-
-This way tests can be written in Chinese language while it is still JavaScript:
-
-```JavaScript
-Feature('CodeceptJS 演示');
-
-Scenario('成功提交表单', ({ 我 }) => {
-    我.在页面('/documentation')
-    我.填写字段('电邮', 'hello@world.com')
-    我.填写字段('密码', '123456')
-    我.勾选选项('激活')
-    我.勾选选项('男');
-    我.单击('创建用户')
-    我.看到('用户名可用')
-    我.在当前网址中看不到('/documentation')
-});
-```
-or
-
-```JavaScript
-Feature('CodeceptJS 演示');
-
-Scenario('成功提交表單', ({ 我 }) => {
-    我.在頁面('/documentation')
-    我.填寫欄位('電郵', 'hello@world.com')
-    我.填寫欄位('密碼', '123456')
-    我.勾選選項('活化')
-    我.勾選選項('男');
-    我.單擊('建立用戶')
-    我.看到('用戶名可用')
-    我.在當前網址中看不到('/documentation')
-});
-```
-
-### Japanese 🇯🇵
-
-Add to `codeceptjs.conf.js` or `codeceptjs.conf.ts` config file:
-
-```js
-  translation: "ja-JP"
-```
-
-Now you can write test like this:
-
-```js
-Scenario('ログインできる', ({ 私は }) => {
-    私は.ページを移動する('/login');
-    私は.フィールドに入力する("Eメール", "foo@example.com");
-    私は.フィールドに入力する("パスワード", "p@ssword");
-    私は.クリックする('ログイン');
-    私は.待つ(1);
-    私は.URLに含まれるか確認する('/home');
-});
-```
-
-## Extending Vocabulary
-
-To add localized aliases to more actions create a new JSON or JavaScript file returning an object with following fields:
-
-```js
-module.exports = {
-  actions: {
-    // add action aliases, translating method name to your language
-    rightClick: 'Rechtsklick'
-  }
-}
-```
-
-Then enable this vocabulary file in codecept conf:
-
-```js
-// inside codecept.conf.js or codecept.conf.ts
-// ...
-  translation: 'de_DE',
-  vocabularies: ['my_translation_file.js'],
-```
-
-### Custom Translation
-
-Create translation file like this:
-
-```js
-module.exports = {
-  I: 'Ya',
-  contexts: {
-    Feature: 'Feature',
-    Scenario: 'Szenario',
-    Before: 'Vor',
-    After: 'Nach',
-    BeforeSuite: 'vor_der_suite',
-    AfterSuite: 'nach_der_suite',
-  },
-  actions: {
-    click: 'Klicken',
-    wait: 'Wartenn',
-  }
-```
-
-And add the file path to your config
-
-```js
-  translation: "MyLang",
-  vocabularies: ["./relative/path/to/your/translation.js"]
-```

package/docs/tutorial.md

@@ -1,271 +0,0 @@
----
-permalink: /tutorial
-title: CodeceptJS Complete Tutorial
----
-
-# Tutorial: Writing Tests for Checkout Page
-
-**[CodeceptJS](https://codecept.io) is a popular open-source testing framework** for JavaScript. It is designed to simplify writing and maintain end-to-end tests for web applications, using a readable and intuitive syntax. To run tests in browser it uses **[Playwright](https://playwright.dev)** by default but ca execute tests via WebDriver, Puppeteer or Appium.
-
-## Let's get CodeceptJS installed!
-
-To install CodeceptJS, you will need to have Node.js and npm (the Node.js package manager) installed on your system. You can check if you already have these tools installed by running the following commands in a terminal:
-
-```bash
-node --version
-npm --version
-```
-
-If either of these commands return an error, you will need to install Node.js and npm before you can install CodeceptJS. You can download and install the latest version of Node.js from the official website, which includes npm.
-
-To install CodeceptJS create a new folder and run command form terminal:
-
-```
-npx create-codeceptjs .
-```
-
-If you run the npx create-codeceptjs . command, it will install CodeceptJS with Playwright in the current directory. 
-
-> The `npx` command is a tool that comes with npm (the Node.js package manager) and it allows you to run npm packages without having to install them globally on your system.
-
-It may take some time as it downloads browsers: Chrome, Firefox and Safari and creates a demo project.
-
-But we are here to write a checkout test, right?
-
-Let's initialize a new project for that!
-
-Run 
-
-```
-npx codeceptjs init
-```
-Agree on defaults (press Enter for every question asked). When asked for base site URL, provide a URL of a ecommerce website you are testing. For instance, it could be: `https://myshop.com` if you test already published website or `http://localhost` if you run the website locally. 
-
-When asked for a test name and suite name write "Checkout". It will create the following dirctory structure:
-
-```
-.
-├── codecept.conf.js
-├── package.json
-└── Checkout_test.js
-```
-
-The `codecept.conf.js` file in the root of the project directory contains the global configuration settings for CodeceptJS.
-
-Now open a test:
-
-```js
-Feature('Checkout');
-
-Scenario('test something', ({ I }) => {
-});
-```
-Inside the Scenario block you write a test. 
-
-Add `I.amOnPage('/')` into it. It will open the browser on a URL you specified as a base.
-
-```js
-Feature('Checkout');
-
-Scenario('test something', ({ I }) => {
-  I.amOnPage('/')
-});
-```
-But you may want to ask...
-
-## What is I?
-
-Glad you asked! 
-
-In CodeceptJS, the `I` object is used to represent the user performing actions in a test scenario. It provides a number of methods (also known as actions) that can be used to simulate user interactions with the application under test.
-
-Some of the most popular actions of the I object are:
-
-* `I.amOnPage(url)`: This action navigates the user to the specified URL.
-* `I.click(locator)`: This action simulates a click on the element identified by the given locator.
-* `I.fillField(field, value)`: This action fills the specified field with the given value.
-* `I.see(text, context)`: This action checks that the given text is visible on the page (or in the specified context).
-* `I.selectOption(select, option)`: This action selects the specified option from the given select dropdown.
-* `I.waitForElement(locator, timeout)`: This action waits for the specified element to appear on the page, up to the given timeout.
-* `I.waitForText(text, timeout, context)`: This action waits for the given text to appear on the page (or in the specified context), up to the given timeout.
-
-We will need to use them to navigate into Checkout process. How do we navigate web? Sure by clicking on links!
-
-Let's use `I.click()` for that.
-
-But how we can access elements on a webpage? 
-
-CodeceptJS is smart enough to locate clickable elements by their visible text. For instance, if on your ecommerce website you have a product 'Coffee Cup' with that exact name you can use 
-
-```js
-I.click('Coffee Cup');
-```
-
-But sometimes elements are not as easy to locate, so you can use CSS or XPath locators to locate them.
-
-For instance, locating Coffee Cup via CSS can take into accont HTML structure of a page and element attributes. For instance, it can be like this:
-
-```js
-I.click('div.products a.product-name[title="Coffee Cup"]');
-```
-
-In this example, the `div.products` part of the selector specifies a div element with the `products` class, and the `a.product-name[title="Coffee Cup"]` part specifies an a element with `the product-name` class and the `title` attribute set to Coffee Cup. 
-
-You can read more about HTML and CSS locators, and basically that's all what you need to know to start writing a checkout test!
-
-## Get back to Checkout
-
-Let's see how a regular checkout script may look in CodeceptJS:
-
-```js
-Scenario('test the checkout form', async ({ I }) => {
-  // we select one product and switched to checkout project
-  I.amOnPage('/');
-  I.click('Coffee Cup');
-  I.click('Purchase');
-  I.click('Checkout');
-
-  // fill in the shipping address
-  I.fillField('First Name', 'John');
-  I.fillField('Last Name', 'Doe');
-  I.fillField('Address', '123 Main St.');
-  I.fillField('City', 'New York');
-  I.selectOption('State', 'New York');
-  I.fillField('Zip Code', '10001');
-
-  // select a payment method
-  I.click('#credit-card-option');
-  I.fillField('Card Number', '1234-5678-9012-3456');
-  I.fillField('Expiration Date', '12/22');
-  I.fillField('Security Code', '123');
-
-  // click the checkout button
-  I.click('Checkout');
-
-  // verify that the checkout was successful
-  I.see('Your order has been placed successfully!');
-});
-``` 
-Sure, in relaity your script might be more complicated. As you have noticed, we used CSS locator `'#credit-card-option'`  to get select a payment option. However, the test is simple and you can follow user steps through it.
-
-Please note, that you shouldn't use a real credit card number here. Good news, you don't need to. Payment providers like Strip provide dummy card numbers for testing purposes. 
-
-Run the test with next command:
-
-```
-npx codeceptjs run --debug -p pauseOnFail
-```
-
-What are special options here?
-
-* `--debug` flag is used to output additional information to the console, such as the details of each step in the test, the values of variables, and the results of test assertions. This can help you to identify and fix any issues in your tests.
-* `-p pauseOnFail` option is also used to keep the browser opened even if a test fails. It will help us to identify to which point test was executed and what can be improved.
-
-Add more test steps if needed, update locators, and notify business owners that all that purchases are made by you so your collegues won't call you in the night asking when you want to get a coffee cup 😀 Also the good idea is to run tests on staging website, to not interfere with business process.
-
-What a test is complete you can run it with:
-
-```
-npx codeceptjs run
-```
-
-If you are annoyed to see a browser window you can use `HEADLESS` environment variable:
-
-```
-HEADLESS=true codeceptjs run
-```
-for Windows users HEADLESS should be set in a different manner:
-
-```
-set HEADLESS=true&& codeceptjs run
-```
-The tests will pass but no browser is shown, so you can watch YouTube videos while it goes!
-
-## Refactoring
-
-What if you need to check more purchases? Should you copy paste your code for that?
-
-No! You can use Page Object pattern to put repeating interactions into the reusable functions.
-
-You can create a page object via next command:
-
-```
-npx codeceptjs gpo
-```
-
-Sure, we will call it `Checkout`. It will be created in `./pages/Checkout.js` file. You should enable it in `codecept.conf.js` inside `include` section:
-
-```js
-    include: {
-    ...
-      checkoutPage: './pages/Checkout.js',
-    },
-
-```
-Now open this file:
-
-```js
-const { I } = inject();
-
-module.exports = {
-
-  // insert your locators and methods here
-}
-```
-
-Feels really empty. What should we do about it? Should we write more code? No, we already have it. Let's copy code blocks from a test we have it and place them under a corredponnding function names:
-
-```js
-const { I } = inject();
-
-module.exports = {
-
-  fillShippingAddress(name, address, city, state, zip) {
-    I.fillField('Name', name);
-    I.fillField('Address', address);
-    I.fillField('City', city);
-    I.fillField('State', state);
-    I.fillField('Zip', zip);
-  },
-
-  fillValidCreditCard() {
-    I.click('#credit-card-option');
-    I.fillField('Card Number', '1234-5678-9012-3456');
-    I.fillField('Expiration Date', '12/22');
-    I.fillField('Security Code', '123');
-  },
-
-  checkout() {
-    I.click('Checkout');
-  },
-}
-```
-
-After that we can update our test to use the created page object. Note, that we import Checkout PageObject by its name `checkoutPage` we previously defined in a config.
-
-```js
-Scenario('test the checkout form', async ({I, checkoutPage}) => {
-  I.amOnPage('/');
-  I.click('Coffee Cup');
-  I.click('Purchase');
-  I.click('Checkout');
-
-  // fill in the shipping address using the page object
-  checkoutPage.fillShippingAddress('John', 'Doe', '123 Main St.', 'New York', 'New York', '10001');
-  checkoutPage.fillValidCreditCard();
-  checkoutPage.checkout();
-
-  // verify that the checkout was successful
-  I.see('Your order has been placed successfully!');
-});
-```
-
-As you see the code of a test was reduced. And we can write the similar tests on the same manner.
-
-By applying more and more cases you can test a website to all behaviors.
-
-## Summary
-
-If you think on just starting test automation, CodeceptJS is the best choice for you as it uses native language to pass commands to browser. 
-
-If you already skilled in JavaScript, with CodeceptJS you can focus on business level of your test, instead of writing code for browser. This way you can keep your tests stable and maintainable.