codeceptjs 3.3.6 → 3.3.7

package/docs/helpers/Puppeteer.md

@@ -2096,7 +2096,7 @@ I.waitUrlEquals('http://127.0.0.1:8000/info');
 -   `sec` **[number][8]** (optional, `1` by default) time in seconds to wait
     ⚠️ returns a _promise_ which is synchronized internally by recorder 
 
-: https://github.com/GoogleChrome/puppeteer
+[1]: https://github.com/GoogleChrome/puppeteer
 
 [2]: https://codecept.io/helpers/Puppeteer-firefox
 

package/docs/helpers/REST.md

@@ -202,7 +202,7 @@ I.setRequestTimeout(10000); // In milliseconds
 
 -   `newTimeout` **[number][5]** timeout in milliseconds
 
-: https://github.com/axios/axios
+[1]: https://github.com/axios/axios
 
 [2]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise
 

package/docs/helpers/WebDriver.md

@@ -32,7 +32,7 @@ Type: [object][16]
 -   `host` **[string][17]?** WebDriver host to connect.
 -   `port` **[number][20]?** WebDriver port to connect.
 -   `protocol` **[string][17]?** protocol for WebDriver server.
--   `path` **[string][17]?** path to WebDriver server,
+-   `path` **[string][17]?** path to WebDriver server.
 -   `restart` **[boolean][29]?** restart browser between tests.
 -   `smartWait` **([boolean][29] | [number][20])?** **enables [SmartWait][33]**; wait for additional milliseconds for element to appear. Enable for 5 secs: "smartWait": 5000.
 -   `disableScreenshots` **[boolean][29]?** don't save screenshots on failure.
@@ -2250,7 +2250,7 @@ I.waitUrlEquals('http://127.0.0.1:8000/info');
 -   `sec` **[number][20]** (optional, `1` by default) time in seconds to wait
     ⚠️ returns a _promise_ which is synchronized internally by recorder 
 
-: http://webdriver.io/
+[1]: http://webdriver.io/
 
 [2]: https://codecept.io/webdriver/#testing-with-webdriver
 

package/docs/playwright.md

@@ -580,6 +580,20 @@ async setPermissions() {
 
 > [▶ Learn more about Helpers](https://codecept.io/helpers/)
 
+## Timezone change
+
+Sometimes it's useful to test browser in different timezones. You can change timezone this way:
+
+```js
+Scenario("Test in a different timezone", ({ I }) => {
+  I.restartBrowser({ timezoneId: 'America/Phoenix' });
+  I.amOnPage("/");
+  // ...
+  // Reset timezone to default one (taken from OS)
+  I.restartBrowser();
+});
+```
+Other context options: https://playwright.dev/docs/api/class-browser#browser-new-context
 
 ## Configuring CI
 

package/docs/quickstart.md

@@ -62,26 +62,53 @@ After CodeceptJS is installed, try running **demo tests** using this commands:
 
 ---
 
+### Init
+
 To start a new project initialize CodeceptJS to create main config file: `codecept.conf.js`.
 
 ```
 npx codeceptjs init
 ```
 
-Answer questions, agree on defaults, when asked to select helpers choose **Playwright**.
+Answer questions, agree on defaults:
+
+
+| Question | Default Answer  | Alternative
+|---|---|---|
+| Do you plan to write tests in TypeScript?  | **n** (No)  | or [learn how to use TypeScript](/typescript)
+| Where are your tests located? | `**./*_test.js` | or any glob pattern like `**.spec.js`
+| What helpers do you want to use? | **Playwright** | Which helper to use for: [web testing](https://codecept.io/basics/#architecture), [mobile testing](https://codecept.io/mobile/), [API testing](https://codecept.io/api/)
+| Where should logs, screenshots, and reports to be stored? | `./output` | path to store artifacts and temporary files 
+| Do you want to enable localization for tests? | **n** English (no localization) | or write [localized tests](https://codecept.io/translation/) in your language
+  
+
+Sample output:
 
+```js
+? Do you plan to write tests in TypeScript? 'No'
+? Where are your tests located? '**./*_test.js'
+? What helpers do you want to use? 'Playwright'
+? Where should logs, screenshots, and reports to be stored? '**./output**'
+? Do you want to enable localization for tests? 'English (no localization)'
 ```
-? What helpers do you want to use?
-❯◉ Playwright
- ◯ WebDriver
- ◯ Puppeteer
- ◯ Puppeteer
- ◯ Appium
- ◯ Nightmare
- ◯ FileSystem
- ```
-
-Create first feature and test when asked.
+
+For Playwright helper provide a website to be tested and browser to be used:
+
+| Question | Default Answer  | Alternative
+|---|---|---|
+| Base url of site to be tested | http://localhost | Base URL of website you plan to test. Use http://github.com or [sample checkout page](https://getbootstrap.com/docs/5.2/examples/checkout/) if you just want to play around
+| Show browser window | **y** Yes | or run browser in **headless mode** 
+| Browser in which testing will be performed | **chromium** | or run tests in firefox, webkit (which is opensource version of Safari) or launch electron app
+
+```js
+? [Playwright] Base url of site to be tested 'http://mysite.com'
+? [Playwright] Show browser window 'Yes'
+? [Playwright] Browser in which testing will be performed. Possible options: chromium, firefox, webkit or electron 'chromium'
+
+```
+
+Create first feature and test when asked
+
 Open a newly created file in your favorite JavaScript editor. 
 The file should look like this:
 
@@ -106,7 +133,7 @@ Scenario('test something', ({ I }) => {
 Run a test:
 
 ```
-npm run codeceptjs
+npx codeceptjs run
 ```
 
 The output should be similar to this:

package/docs/translation.md

@@ -3,55 +3,58 @@ permalink: /translation
 title: Translation
 ---
 
-> 🌍 Since CodeceptJS 2.4.2 you can use translation for `Scenario`, `Before`, and other keywords within your tests. Please help us to update language definition files to include the best translation for your language!
+# 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/master/translations).
+🇩🇪🇯🇵🇫🇷🇹🇼🇨🇳🇵🇱🇧🇷🇮🇹
 
-Please refer to translated steps inside translation files and send Pull Requests to add missing.
+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.
 
-To get autocompletion for localized method names generate definitions by running
+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.
 
-```sh
-npx codeceptjs def
-```
+## How it works
 
-## Russian
+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.
 
-Add to config:
+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.
 
-```json
-  "translation": "ru-RU"
-```
+You can enable translation if your team is not from English-speaking country developing non-English product.
 
-when running with `--steps` option steps output will be translated:
+> ⚠️ 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).
 
-![steps-in-russian](/img/translate-ru1.png)
+To enable translition create a new project with 
 
-This also enables localized method names for actor object.
+```
+npx codeceptjs init
+```
 
-This way tests can be written in native language while it is still JavaScript:
+And select a language of your choice from a list:
 
-```js
-Сценарий('пробую написать реферат', (Я) => {
-    Я.на_странице('https://yandex.ru/referats');
-    Я.вижу("Написать реферат по");
-    Я.выбираю_опцию('Психологии');
-    Я.кликаю("Написать реферат");
-    Я.вижу("Реферат по психологии");
-});
 ```
+? 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).
+
 
-## Portuguese
+## Languages
+
+### Portuguese 🇧🇷
 
 To write your tests in portuguese you can enable the portuguese translation in config file like:
 
-```json
-  "translation": "pt-BR"
+```js
+  translation: "pt-BR"
 ```
 
 Now you can write test like this:
@@ -66,12 +69,12 @@ Cenário('Efetuar login', ({ Eu }) => {
 });
 ```
 
-## French
+### French 🇫🇷
 
 To write your tests in French you can enable the French translation by adding to config:
 
-```json
-  "translation": "fr-FR"
+```js
+  translation: "fr-FR"
 ```
 
 Now you can write tests like this:
@@ -86,12 +89,12 @@ Scenario('Se connecter sur GitHub', (Je) => {
 });
 ```
 
-## Italian
+### Italian 🇮🇹
 
-Add to config
+Add to `codeceptjs.conf.js` or `codeceptjs.conf.ts` config file:
 
-```json
-  "translation": "it-IT"
+```js
+  translation: "it-IT"
 ```
 
 Now you can write test like this:
@@ -106,12 +109,12 @@ Caratteristica('Effettuare il Login su GitHub', (io) => {
 });
 ```
 
-## Polish
+### Polish 🇵🇱
 
-Add to config
+Add to `codeceptjs.conf.js` or `codeceptjs.conf.ts` config file:
 
-```json
-  "translation": "pl-PL"
+```js
+  translation: "pl-PL"
 ```
 
 Now you can write test like this:
@@ -127,16 +130,16 @@ Scenario('Zakładanie konta free trial na stronie głównej GetResponse', ({ Ja
 });
 ```
 
-## Chinese
+### Chinese 🇹🇼🇨🇳
 
-Add to config:
+Add to `codeceptjs.conf.js` or `codeceptjs.conf.ts` config: file:
 
-```JSON
-  "translation": "zh-CN"
+```JS
+  translation: "zh-CN"
 ```
 or
-```JSON
-  "translation": "zh-TW"
+```JS
+  translation: "zh-TW"
 ```
 
 This way tests can be written in Chinese language while it is still JavaScript:
@@ -156,6 +159,7 @@ Scenario('成功提交表单', ({ 我 }) => {
 });
 ```
 or
+
 ```JavaScript
 Feature('CodeceptJS 演示');
 
@@ -171,12 +175,12 @@ Scenario('成功提交表單', ({ 我 }) => {
 });
 ```
 
-## Japanese
+### Japanese 🇯🇵
 
-Add to config
+Add to `codeceptjs.conf.js` or `codeceptjs.conf.ts` config file:
 
-```json
-  "translation": "ja-JP"
+```js
+  translation: "ja-JP"
 ```
 
 Now you can write test like this:
@@ -192,13 +196,35 @@ Scenario('ログインできる', ({ 私は }) => {
 });
 ```
 
-## Using your own translation file
+## 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: '',
+  I: 'Ya',
   contexts: {
     Feature: 'Feature',
     Scenario: 'Szenario',
@@ -215,6 +241,7 @@ module.exports = {
 
 And add the file path to your config
 
-```json
-    "translation": "./path/to/your/translation.js"
+```js
+  translation: "MyLang",
+  vocabularies: ["./relative/path/to/your/translation.js"]
 ```

package/docs/typescript.md

@@ -41,8 +41,55 @@ Then select TypeScript as the first question:
 
 Then a config file and new tests will be created in TypeScript format.
 
-If a config file is set in TypeScrip format (`codecept.conf.ts`) package `node-ts` will be used to run tests. 
+If a config file is set in TypeScript format (`codecept.conf.ts`) package `node-ts` will be used to run tests. 
 
+## Promise-Based Typings
+
+If you plan to write tests in TypeScript you will probably want to enable "promise-based typings" as you will be asked in `init` command about it:
+
+```js
+? Would you prefer to use promise-based typings and explicitly use `await` for all I.* commands?
+```
+
+By default, CodeceptJS tests are written in synchronous mode. This is a regular CodeceptJS test:
+
+```js
+I.amOnPage('/')
+I.click('Login')
+I.see('Hello!')
+```
+
+Even thought we don't see any `await`, those commands are executed synchronously, one by one.
+All methods of `I` object actually return promise and TypeScript linter requires to use `await` operator for those promises.
+To trick TypeScript and allow writing tests in CodeceptJS manner we create typings where `void` is returned instead of promises. This way linter won't complain on async code without await, as no promise is returned. 
+
+Our philosophy here is: use `await` only when it is actually needed, don't add visual mess to your code prefixing each line with `await`. However, you might want to get a better control of your tests and follow TypeScript conventions.
+This is why you might want to **enable promise-based typings**.
+
+A previous test should be rewritten with `await`s:
+
+```js
+await I.amOnPage('/')
+await I.click('Login')
+await I.see('Hello!')
+```
+
+Using `await` explicitly provides a beter control of execution flow. Some CodeceptJS users report that they increased stability of tests by adopting `await` for all CodeceptJS commands in their codebase.
+
+If you select to use promise-based typings, type definitions will be generated so all actions to return a promise. 
+Otherwise they will still return promises but it won't be relfected in type definitions.
+
+To introduce promise-based typings into a current project edit `codecept.conf.ts`:
+
+```ts
+  fullPromiseBased: true;
+```
+
+and rebuild type definitions with
+
+```
+npx codeceptjs def
+```
 
 ## Types for custom helper or page object
 
@@ -51,13 +98,12 @@ If you want to get types for your [custom helper](https://codecept.io/helpers/#c
 For example, if you add the new step `printMessage` for your custom helper like this:
 ```js
 // customHelper.ts
-class CustomHelper extends Helper {
+export class CustomHelper extends Helper {
   printMessage(msg: string) {
     console.log(msg)
   }
 }
 
-export = CustomHelper
 ```
 
 Then you need to add this helper to your `codecept.conf.js` like in this [docs](https://codecept.io/helpers/#configuration).

package/lib/codecept.js

@@ -85,6 +85,7 @@ class Codecept {
       global.Given = stepDefinitions.Given;
       global.When = stepDefinitions.When;
       global.Then = stepDefinitions.Then;
+      global.DefineParameterType = stepDefinitions.defineParameterType;
     }
   }
 
@@ -94,12 +95,13 @@ class Codecept {
   runHooks() {
     // default hooks
     runHook(require('./listener/steps'));
+    runHook(require('./listener/artifacts'));
     runHook(require('./listener/config'));
     runHook(require('./listener/helpers'));
     runHook(require('./listener/timeout'));
     runHook(require('./listener/exit'));
 
-    // custom hooks
+    // custom hooks (previous iteration of plugins)
     this.config.hooks.forEach(hook => runHook(hook));
   }
 

package/lib/command/definitions.js

@@ -138,7 +138,8 @@ module.exports = function (genPath, options) {
       helperPaths[name] = require;
       helperNames.push(name);
     } else {
-      helperNames.push(name);
+      const fullBasedPromised = codecept.config.fullPromiseBased;
+      helperNames.push(fullBasedPromised === true ? `${name}Ts` : name);
     }
 
     if (!actingHelpers.includes(name)) {
@@ -155,6 +156,10 @@ module.exports = function (genPath, options) {
   supportObject.set('I', 'I');
   supportObject.set('current', 'any');
 
+  if (translations.loaded) {
+    supportObject.set(translations.I, translations.I);
+  }
+
   if (autoLogin) {
     supportObject.set(autoLogin, 'any');
   }
@@ -174,7 +179,7 @@ module.exports = function (genPath, options) {
     supportObject.set(name, name);
   }
 
-  const definitionsFileContent = getDefinitionsFileContent({
+  let definitionsFileContent = getDefinitionsFileContent({
     helperNames,
     supportObject,
     importPaths: getImportString(testsPath, targetFolderPath, supportPaths, helperPaths),
@@ -184,6 +189,25 @@ module.exports = function (genPath, options) {
     customHelpers,
   });
 
+  // add aliases for translations
+  if (translations.loaded) {
+    const namespaceTranslationAliases = [];
+    namespaceTranslationAliases.push(`interface ${translations.vocabulary.I} extends WithTranslation<Methods> {}`);
+
+    namespaceTranslationAliases.push('  namespace Translation {');
+    definitionsFileContent = definitionsFileContent.replace('namespace Translation {', namespaceTranslationAliases.join('\n'));
+
+    const translationAliases = [];
+
+    if (translations.vocabulary.contexts) {
+      Object.keys(translations.vocabulary.contexts).forEach(k => {
+        translationAliases.push(`declare const ${translations.vocabulary.contexts[k]}: typeof ${k};`);
+      });
+    }
+
+    definitionsFileContent += `\n${translationAliases.join('\n')}`;
+  }
+
   fs.writeFileSync(path.join(targetFolderPath, 'steps.d.ts'), definitionsFileContent);
   output.print('TypeScript Definitions provide autocompletion in Visual Studio Code and other IDEs');
   output.print('Definitions were generated in steps.d.ts');

package/lib/command/generate.js

@@ -7,6 +7,7 @@ const {
   fileExists, ucfirst, lcfirst, beautify,
 } = require('../utils');
 const output = require('../output');
+const generateDefinitions = require('./definitions');
 const {
   getConfig, getTestRoot, safeFileWrite, readConfig,
 } = require('./utils');
@@ -15,7 +16,7 @@ let extension = 'js';
 
 const testTemplate = `Feature('{{feature}}');
 
-Scenario('test something', ({ {{actor}} }) => {
+Scenario('test something', async ({ {{actor}} }) => {
 
 });
 `;
@@ -55,13 +56,19 @@ module.exports.test = function (genPath) {
     if (!fileExists(dir)) mkdirp.sync(dir);
     let testContent = testTemplate.replace('{{feature}}', result.feature);
 
-    // can be confusing before translations are documented
-    // commenting it out:
-
-    // let container = require('../container');
-    // container.create(config);
-    // testContent = testContent.replace('{{actor}}', container.translation().I);
-    testContent = testContent.replace('{{actor}}', 'I');
+    const container = require('../container');
+    container.create(config, {});
+    // translate scenario test
+    if (container.translation().loaded) {
+      const vocabulary = container.translation().vocabulary;
+      testContent = testContent.replace('{{actor}}', container.translation().I);
+      if (vocabulary.contexts.Feature) testContent = testContent.replace('Feature', vocabulary.contexts.Feature);
+      if (vocabulary.contexts.Scenario) testContent = testContent.replace('Scenario', vocabulary.contexts.Scenario);
+      output.print(`Test was created in ${colors.bold(config.translation)} localization. See: https://codecept.io/translation/`);
+    } else {
+      testContent = testContent.replace('{{actor}}', 'I');
+    }
+    if (!config.fullPromiseBased) testContent = testContent.replace('async', '');
 
     if (!safeFileWrite(testFile, testContent)) return;
     output.success(`\nTest for ${result.filename} was created in ${testFile}`);
@@ -133,7 +140,14 @@ module.exports.pageObject = function (genPath, opts) {
       ${name}: '${result.filename}',
     },`);
 
-    output.print(`Use ${output.colors.bold(colors.cyan(name))} as parameter in test scenarios to access this object`);
+    output.print(`Use ${output.colors.bold(colors.cyan(name))} as parameter in test scenarios to access this object:`);
+    output.print(`\nScenario('my new test', ({ I, ${name} })) { /** ... */ }\n`);
+
+    try {
+      generateDefinitions(testsPath, {});
+    } catch (_err) {
+      output.print(`Run ${colors.green('npx codeceptjs def')} to update your types to get auto-completion for object.`);
+    }
   });
 };