codeceptjs 4.0.0-beta.2 → 4.0.0-beta.20

package/typings/index.d.ts

@@ -1,5 +1,6 @@
 // Project: https://github.com/codeception/codeceptjs/
 /// <reference path="./types.d.ts" />
+/// <reference path="../lib/mocha/types.d.ts" />
 /// <reference path="./promiseBasedTypes.d.ts" />
 /// <reference types="webdriverio" />
 /// <reference path="./Mocha.d.ts" />
@@ -7,137 +8,453 @@
 /// <reference types="playwright" />
 
 declare namespace CodeceptJS {
-  // Utility Types
-  type WithTranslation<T> = T & import("./utils").Translate<T, Translation.Actions>;
+  type WithTranslation<T> = T &
+    // @ts-ignore
+    import('./utils').Translate<T, Translation.Actions>
 
-  // Cookie Type
   type Cookie = {
-    name: string;
-    value: string | boolean;
-    domain?: string;
-    path?: string;
-  };
+    name: string
+    value: string | boolean
+    domain?: string
+    path?: string
+  }
 
-  // Retry Configuration
   type RetryConfig = {
-    grep?: string | RegExp;
-    Feature?: number;
-    Scenario?: number;
-    Before?: number;
-    After?: number;
-    BeforeSuite?: number;
-    AfterSuite?: number;
-  };
-
-  // Timeout Configuration
+    /** Filter tests by string or regexp pattern */
+    grep?: string | RegExp
+    /** Number of times to repeat scenarios of a Feature */
+    Feature?: number
+    /** Number of times to repeat scenarios */
+    Scenario?: number
+    /** Number of times to repeat Before hook */
+    Before?: number
+    /** Number of times to repeat After hook */
+    After?: number
+    /** Number of times to repeat BeforeSuite hook */
+    BeforeSuite?: number
+    /** Number of times to repeat AfterSuite hook */
+    AfterSuite?: number
+  }
+
   type TimeoutConfig = {
-    grep: string | RegExp;
-    Feature: number;
-    Scenario: number;
-  };
+    /** Filter tests by string or regexp pattern */
+    grep: string | RegExp
+    /** Set timeout for a scenarios of a Feature */
+    Feature: number
+    /** Set timeout for scenarios */
+    Scenario: number
+  }
 
-  // AI Configuration
   type AiPrompt = {
-    role: string;
-    content: string;
-  };
+    role: string
+    content: string
+  }
 
   type AiConfig = {
-    request: (messages: any) => Promise<string>;
+    /** request function to send prompts to AI provider */
+    request: (messages: any) => Promise<string>
+
+    /** custom prompts */
     prompts?: {
-      writeStep?: (html: string, input: string) => Array<AiPrompt>;
-      healStep?: (html: string, object) => Array<AiPrompt>;
-      generatePageObject?: (
-        html: string,
-        extraPrompt?: string,
-        rootLocator?: string
-      ) => Array<AiPrompt>;
-    };
-    maxTokens?: number;
+      /** Returns prompt to write CodeceptJS steps inside pause mode  */
+      writeStep?: (html: string, input: string) => Array<AiPrompt>
+      /** Returns prompt to heal step when test fails on CI if healing is on  */
+      healStep?: (html: string, object) => Array<AiPrompt>
+      /** Returns prompt to generate page object inside pause mode  */
+      generatePageObject?: (html: string, extraPrompt?: string, rootLocator?: string) => Array<AiPrompt>
+    }
+
+    /** max tokens to use */
+    maxTokens?: number
+
+    /** configuration for processing HTML for GPT */
     html?: {
-      maxLength?: number;
-      simplify?: boolean;
-      minify?: boolean;
-      interactiveElements?: Array<string>;
-      textElements?: Array<string>;
-      allowedAttrs?: Array<string>;
-      allowedRoles?: Array<string>;
-    };
-  };
-
-  // Main Configuration
+      /** max size of HTML to be sent to OpenAI to avoid token limit */
+      maxLength?: number
+      /** should HTML be changed by removing non-interactive elements */
+      simplify?: boolean
+      /** should HTML be minified before sending */
+      minify?: boolean
+      interactiveElements?: Array<string>
+      textElements?: Array<string>
+      allowedAttrs?: Array<string>
+      allowedRoles?: Array<string>
+    }
+  }
+
   type MainConfig = {
-    tests: string;
-    output: string;
-    emptyOutputFolder?: boolean;
-    grep?: string;
+    /** Pattern to locate CodeceptJS tests.
+     * Allows to enter glob pattern or an Array<string> of patterns to match tests / test file names.
+     *
+     * For tests in JavaScript:
+     *
+     * ```js
+     * tests: 'tests/**.test.js'
+     * ```
+     * For tests in TypeScript:
+     *
+     * ```js
+     * tests: 'tests/**.test.ts'
+     * ```
+     */
+    tests: string | string[]
+    /**
+     * Where to store failure screenshots, artifacts, etc
+     *
+     * ```js
+     * output: './output'
+     * ```
+     */
+    output: string
+    /**
+     * empty output folder for next run
+     *
+     * ```js
+     * emptyOutputFolder: true
+     * ```
+     */
+    emptyOutputFolder?: boolean
+    /**
+     * mask sensitive data in output logs
+     *
+     * ```js
+     * maskSensitiveData: true
+     * ```
+     */
+    maskSensitiveData?: boolean
+    /**
+     * Pattern to filter tests by name.
+     * This option is useful if you plan to use multiple configs for different environments.
+     *
+     * To execute only tests with @firefox tag
+     *
+     * ```js
+     * grep: '@firefox'
+     * ```
+     */
+    grep?: string
+    /**
+     * Enable and configure helpers:
+     *
+     * ```js
+     * helpers: {
+     *   Playwright: {
+     *     url: 'https://mysite.com',
+     *     browser: 'firefox'
+     *   }
+     * }
+     * ```
+     */
     helpers?: {
-      Playwright?: PlaywrightConfig;
-      Puppeteer?: PuppeteerConfig;
-      WebDriver?: WebDriverConfig;
-      REST?: RESTConfig;
-      JSONResponse?: any;
-      AI?: any;
-      [key: string]: any;
-    };
-    plugins?: any;
-    include?: any;
-    timeout?: number | Array<TimeoutConfig> | TimeoutConfig;
-    retry?: number | Array<RetryConfig> | RetryConfig;
-    noGlobals?: boolean;
-    mocha?: any;
-    bootstrap?: (() => Promise<void>) | boolean | string;
-    teardown?: (() => Promise<void>) | boolean | string;
-    bootstrapAll?: (() => Promise<void>) | boolean | string;
-    teardownAll?: (() => Promise<void>) | boolean | string;
-    translation?: string;
-    vocabularies?: Array<string>;
-    require?: Array<string>;
+      /**
+       * Run web tests controlling browsers via Playwright engine.
+       *
+       * https://codecept.io/helpers/playwright
+       *
+       * Available commands:
+       * ```js
+       * I.amOnPage('/');
+       * I.click('Open');
+       * I.see('Welcome');
+       * ```
+       */
+      Playwright?: PlaywrightConfig
+      /**
+       * Run web tests controlling browsers via Puppeteer engine.
+       *
+       * https://codecept.io/helpers/puppeteer
+       *
+       * Available commands:
+       * ```js
+       * I.amOnPage('/');
+       * I.click('Open');
+       * I.see('Welcome');
+       * ```
+       */
+      Puppeteer?: PuppeteerConfig
+
+      /**
+       * Run web tests controlling browsers via WebDriver engine.
+       *
+       * Available commands:
+       * ```js
+       * I.amOnPage('/');
+       * I.click('Open');
+       * I.see('Welcome');
+       * ```
+       *
+       * https://codecept.io/helpers/webdriver
+       */
+      WebDriver?: WebDriverConfig
+      /**
+       * Execute REST API requests for API testing or to assist web testing.
+       *
+       * https://codecept.io/helpers/REST
+       *
+       * Available commands:
+       * ```js
+       * I.sendGetRequest('/');
+       * ```
+       */
+      REST?: RESTConfig
+
+      /**
+       * Use JSON assertions for API testing.
+       * Can be paired with REST or GraphQL helpers.
+       *
+       * https://codecept.io/helpers/JSONResponse
+       *
+       * Available commands:
+       * ```js
+       * I.seeResponseContainsJson({ user: { email: 'jon@doe.com' } });
+       * ```
+       */
+      JSONResponse?: any
+
+      /** Enable AI features for development purposes */
+      AI?: any
+
+      [key: string]: any
+    }
+    /**
+     * Enable CodeceptJS plugins.
+     *
+     * https://codecept.io/plugins/
+     *
+     * Plugins listen to test events and extend functionality of CodeceptJS.
+     *
+     * Example:
+     *
+     * ```js
+     * plugins: {
+     *   autoDelay: {
+     *     enabled: true
+     *   }
+      }
+     * ```
+     */
+    plugins?: any
+    /**
+     * Include page objects to access them via dependency injection
+     *
+     * ```js
+     * I: "./custom_steps.js",
+     * loginPage: "./pages/Login.js",
+     * User: "./pages/User.js",
+     * ```
+     * Configured modules can be injected by name in a Scenario:
+     *
+     * ```js
+     * Scenario('test', { I, loginPage, User })
+     * ```
+     */
+    include?: any
+    /**
+     * Set default tests timeout in seconds.
+     * Tests will be killed on no response after timeout.
+     *
+     * ```js
+     * timeout: 20,
+     * ```
+     *
+     * Can be customized to use different timeouts for a subset of tests:
+     *
+     * ```js
+     * timeout: [
+     *    10,
+     *    {
+     *      grep: '@slow',
+     *      Scenario: 20
+     *    }
+     * ]
+     * ```
+     */
+    timeout?: number | Array<TimeoutConfig> | TimeoutConfig
+
+    /**
+     * Configure retry strategy for tests
+     *
+     * To retry all tests 3 times:
+     *
+     * ```js
+     * retry: 3
+     * ```
+     *
+     * To retry only Before hook 3 times:
+     *
+     * ```js
+     * retry: {
+     *    Before: 3
+     * }
+     * ```
+     *
+     * To retry tests marked as flaky 3 times, other 1 time:
+     *
+     * ```js
+     * retry: [
+     *   {
+     *     Scenario: 1,
+     *     Before: 1
+     *   },
+     *   {
+     *     grep: '@flaky',
+     *     Scenario: 3
+     *     Before: 3
+     *   }
+     * ]
+     * ```
+     */
+    retry?: number | Array<RetryConfig> | RetryConfig
+
+    /** Disable registering global functions (Before, Scenario, etc). Not recommended */
+    noGlobals?: boolean
+    /**
+     * [Mocha test runner options](https://mochajs.org/#configuring-mocha-nodejs), additional [reporters](https://codecept.io/reports/#xml) can be configured here.
+     *
+     * Example:
+     *
+     * ```js
+     * mocha: {
+     *   "mocha-junit-reporter": {
+     *      stdout: "./output/console.log",
+     *      options: {
+     *        mochaFile: "./output/result.xml",
+     *        attachments: true //add screenshot for a failed test
+     *      }
+     *   }
+     * }
+     * ```
+     */
+    mocha?: any
+    /**
+     * [Execute code before](https://codecept.io/bootstrap/) tests are run.
+     *
+     * Can be either JS module file or async function:
+     *
+     * ```js
+     * bootstrap: async () => server.launch(),
+     * ```
+     * or
+     * ```js
+     * bootstrap: 'bootstrap.js',
+     * ```
+     */
+    bootstrap?: (() => Promise<void>) | boolean | string
+    /**
+     * [Execute code after tests](https://codecept.io/bootstrap/) finished.
+     *
+     * Can be either JS module file or async function:
+     *
+     * ```js
+     * teardown: async () => server.stop(),
+     * ```
+     * or
+     * ```js
+     * teardown: 'teardown.js',
+     * ```
+     */
+    teardown?: (() => Promise<void>) | boolean | string
+    /**
+     * [Execute code before launching tests in parallel mode](https://codecept.io/bootstrap/#bootstrapall-teardownall)
+     *
+     */
+    bootstrapAll?: (() => Promise<void>) | boolean | string
+    /**
+     * [Execute JS code after finishing tests in parallel mode](https://codecept.io/bootstrap/#bootstrapall-teardownall)
+     */
+    teardownAll?: (() => Promise<void>) | boolean | string
+
+    /** Enable [localized test commands](https://codecept.io/translation/) */
+    translation?: string
+
+    /** Additional vocabularies for [localication](https://codecept.io/translation/) */
+    vocabularies?: Array<string>
+
+    /**
+     * [Require additional JS modules](https://codecept.io/configuration/#require)
+     *
+     * Example:
+     * ```
+     * require: ["should"]
+     * ```
+     */
+    require?: Array<string>
+
+    /**
+     * Enable [BDD features](https://codecept.io/bdd/#configuration).
+     *
+     * Sample configuration:
+     * ```js
+     * gherkin: {
+     *   features: "./features/*.feature",
+     *   steps: ["./step_definitions/steps.js"]
+     * }
+     * ```
+     */
     gherkin?: {
-      features: string | Array<string>;
-      steps: string | Array<string>;
-    };
-    ai?: AiConfig;
-    fullPromiseBased?: boolean;
-    [key: string]: any;
-  };
-
-  // Mocking
+      /** load feature files by pattern. Multiple patterns can be specified as array */
+      features: string | Array<string>
+      /** load step definitions from JS files */
+      steps: string | Array<string>
+    }
+
+    /**
+     * [AI](https://codecept.io/ai/) features configuration.
+     */
+    ai?: AiConfig
+
+    /**
+     * Enable full promise-based helper methods for [TypeScript](https://codecept.io/typescript/) project.
+     * If true, all helper methods are typed as asynchronous;
+     * Otherwise, it remains as it works in versions prior to 3.3.6
+     */
+    fullPromiseBased?: boolean
+
+    [key: string]: any
+  }
+
   type MockRequest = {
-    method: 'GET' | 'PUT' | 'POST' | 'PATCH' | 'DELETE' | string;
-    path: string;
-    queryParams?: object;
-  };
+    method: 'GET' | 'PUT' | 'POST' | 'PATCH' | 'DELETE' | string
+    path: string
+    queryParams?: object
+  }
 
   type MockResponse = {
-    status: number;
-    body?: object;
-  };
+    status: number
+    body?: object
+  }
 
   type MockInteraction = {
-    request: MockRequest;
-    response: MockResponse;
-  };
+    request: MockRequest
+    response: MockResponse
+  }
 
-  // Page Scroll
   interface PageScrollPosition {
-    x: number;
-    y: number;
+    x: number
+    y: number
   }
 
-  // Actors and Support
+  // Could get extended by user generated typings
   interface Methods extends ActorStatic {}
   interface I {}
   interface IHook {}
   interface IScenario {}
   interface IFeature {
-    (title: string): FeatureConfig;
+    (title: string, opts?: { [key: string]: any }): FeatureConfig
   }
+  interface CallbackOrder extends Array<any> {}
   interface SupportObject {
-    I: CodeceptJS.I;
+    I: CodeceptJS.I
+  }
+  namespace Translation {
+    interface Actions {}
   }
 
-  // Locator Types
+  // Extending JSDoc generated typings
+
+  // Types who are not be defined by JSDoc
+  type actor = <T extends { [action: string]: (...args: any[]) => void }>(customSteps?: T & ThisType<WithTranslation<Methods & T>>) => WithTranslation<Methods & T>
+
   type ILocator =
     | { id: string }
     | { xpath: string }
@@ -146,144 +463,188 @@ declare namespace CodeceptJS {
     | { frame: string }
     | { android: string }
     | { ios: string }
+    | { android: string; ios: string }
     | { react: string }
     | { vue: string }
     | { shadow: string[] }
     | { custom: string }
-    | { pw: string };
-
-  type LocatorOrString = string | ILocator | OtherLocators | CustomLocators[keyof CustomLocators];
+    | { pw: string }
+  interface CustomLocators {}
+  interface OtherLocators {
+    props?: object
+  }
+  type LocatorOrString = string | ILocator | Locator | OtherLocators | CustomLocators[keyof CustomLocators]
 
-  type StringOrSecret = string | CodeceptJS.Secret;
+  type StringOrSecret = string | CodeceptJS.Secret
 
-  // Hook and Scenario Callbacks
   interface HookCallback {
-    (args: SupportObject): void | Promise<void>;
+    (args: SupportObject): void | Promise<void>
   }
-
   interface Scenario extends IScenario {
-    only: IScenario;
-    skip: IScenario;
-    todo: IScenario;
+    only: IScenario
+    skip: IScenario
+    todo: IScenario
   }
-
   interface Feature extends IFeature {
-    skip: IFeature;
+    only: IFeature
+    skip: IFeature
   }
-
   interface IData {
-    Scenario: IScenario;
-    only: { Scenario: IScenario };
+    Scenario: IScenario
+    only: { Scenario: IScenario }
   }
 
-  // Scenario Interface
   interface IScenario {
-    (title: string, callback?: HookCallback): ScenarioConfig;
-    (
-      title: string,
-      opts: { [key: string]: any },
-      callback: HookCallback
-    ): ScenarioConfig;
+    // Scenario.todo can be called only with a title.
+    (title: string, callback?: HookCallback): ScenarioConfig
+    (title: string, opts: { [key: string]: any }, callback: HookCallback): ScenarioConfig
   }
-
   interface IHook {
-    (callback: HookCallback): void;
+    (callback: HookCallback): HookConfig
   }
 
-  // Global Utilities
   interface Globals {
-    codeceptjs: typeof codeceptjs;
+    codeceptjs: typeof codeceptjs
   }
 
-  // BDD Parameter Types
   interface IParameterTypeDefinition<T> {
-    name: string;
-    regexp: readonly RegExp[] | readonly string[] | RegExp | string;
-    transformer: (...match: string[]) => T;
-    useForSnippets?: boolean;
-    preferForRegexpMatch?: boolean;
+    name: string
+    regexp: readonly RegExp[] | readonly string[] | RegExp | string
+    transformer: (...match: string[]) => T
+    useForSnippets?: boolean
+    preferForRegexpMatch?: boolean
+  }
+
+  interface HookConfig {
+    retry(retries?: number): HookConfig
   }
+
+  function addStep(step: string, fn: Function): Promise<void>
 }
 
+type TryTo = <T>(fn: () => Promise<T> | T) => Promise<T | false>
+type HopeThat = <T>(fn: () => Promise<T> | T) => Promise<T | false>
+type RetryTo = <T>(fn: () => Promise<T> | T, retries?: number) => Promise<T>
+
 // Globals
-declare const codecept_dir: string;
-declare const output_dir: string;
-declare function tryTo<T>(...fn: unknown[]): Promise<T>;
-declare function retryTo<T>(...fn: unknown[]): Promise<T>;
-
-declare const actor: CodeceptJS.actor;
-declare const Helper: typeof CodeceptJS.Helper;
-declare const pause: typeof CodeceptJS.pause;
-declare const within: typeof CodeceptJS.within;
-declare const session: typeof CodeceptJS.session;
-declare const DataTable: typeof CodeceptJS.DataTable;
-declare const locate: typeof CodeceptJS.Locator.build;
-declare const secret: typeof CodeceptJS.Secret.secret;
+declare const codecept_dir: string
+declare const output_dir: string
+declare const tryTo: TryTo
+declare const retryTo: RetryTo
+declare const hopeThat: HopeThat
+
+declare const actor: CodeceptJS.actor
+declare const codecept_actor: CodeceptJS.actor
+declare const Helper: typeof CodeceptJS.Helper
+declare const codecept_helper: typeof CodeceptJS.Helper
+declare const pause: typeof CodeceptJS.pause
+declare const within: typeof CodeceptJS.within
+declare const session: typeof CodeceptJS.session
+declare const DataTable: typeof CodeceptJS.DataTable
+declare const DataTableArgument: typeof CodeceptJS.DataTableArgument
+declare const codeceptjs: typeof CodeceptJS
+declare const locate: typeof CodeceptJS.Locator.build
+declare function inject(): CodeceptJS.SupportObject
+declare function inject<T extends keyof CodeceptJS.SupportObject>(name: T): CodeceptJS.SupportObject[T]
+declare const secret: typeof CodeceptJS.Secret.secret
 
 // BDD
-declare const Given: typeof CodeceptJS.addStep;
-declare const When: typeof CodeceptJS.addStep;
-declare const Then: typeof CodeceptJS.addStep;
+declare const Given: typeof CodeceptJS.addStep
+declare const When: typeof CodeceptJS.addStep
+declare const Then: typeof CodeceptJS.addStep
+
+declare const Feature: CodeceptJS.Feature
+declare const Scenario: CodeceptJS.Scenario
+declare const xScenario: CodeceptJS.IScenario
+declare const xFeature: CodeceptJS.IFeature
+declare function Data(data: any): CodeceptJS.IData
+declare function xData(data: any): CodeceptJS.IData
+declare function DefineParameterType(options: CodeceptJS.IParameterTypeDefinition<any>): void
 
 // Hooks
-declare const BeforeSuite: CodeceptJS.IHook;
-declare const AfterSuite: CodeceptJS.IHook;
-declare const Before: CodeceptJS.IHook;
-declare const After: CodeceptJS.IHook;
+declare const BeforeSuite: CodeceptJS.IHook
+declare const AfterSuite: CodeceptJS.IHook
+declare const Background: CodeceptJS.IHook
+declare const Before: CodeceptJS.IHook
+declare const After: CodeceptJS.IHook
+
+// Plugins
+declare const __: any
+
+interface Window {
+  resq: any
+}
 
-// Process Interface
 declare namespace NodeJS {
   interface Process {
-    profile?: string;
-    env?: {
-      [key: string]: string | undefined;
-    };
+    profile: string
   }
 
   interface Global extends CodeceptJS.Globals {
-    codecept_dir: typeof codecept_dir;
-    output_dir: typeof output_dir;
-    actor: typeof actor;
-    Helper: typeof Helper;
-    pause: typeof pause;
-    within: typeof within;
-    session: typeof session;
-    DataTable: typeof DataTable;
-    locate: typeof locate;
-    secret: typeof secret;
-    tryTo: typeof tryTo;
-    retryTo: typeof retryTo;
-    Given: typeof Given;
-    When: typeof When;
-    Then: typeof Then;
+    codecept_dir: typeof codecept_dir
+    output_dir: typeof output_dir
+
+    actor: typeof actor
+    codecept_actor: typeof codecept_actor
+    Helper: typeof Helper
+    codecept_helper: typeof codecept_helper
+    pause: typeof pause
+    within: typeof within
+    session: typeof session
+    DataTable: typeof DataTable
+    DataTableArgument: typeof DataTableArgument
+    locate: typeof locate
+    inject: typeof inject
+    secret: typeof secret
+    // plugins
+    tryTo: typeof tryTo
+    retryTo: typeof retryTo
+
+    // BDD
+    Given: typeof Given
+    When: typeof When
+    Then: typeof Then
+    DefineParameterType: typeof DefineParameterType
   }
 }
 
 declare namespace Mocha {
   interface MochaGlobals {
-    Feature: typeof Feature;
-    Scenario: typeof Scenario;
-    BeforeSuite: typeof BeforeSuite;
-    AfterSuite: typeof AfterSuite;
-    Before: typeof Before;
-    After: typeof After;
+    Feature: typeof Feature
+    Scenario: typeof Scenario
+    xFeature: typeof xFeature
+    xScenario: typeof xScenario
+    Data: typeof Data
+    xData: typeof xData
+    BeforeSuite: typeof BeforeSuite
+    AfterSuite: typeof AfterSuite
+    Background: typeof Background
+    Before: typeof Before
+    After: typeof After
   }
 
   interface Suite extends SuiteRunnable {
-    tags?: any[];
-    feature?: any;
+    tags: any[]
+    comment: string
+    feature: any
   }
 
   interface Test extends Runnable {
-    artifacts?: [];
-    tags?: any[];
+    artifacts: []
+    tags: any[]
   }
 }
 
-declare module "codeceptjs" {
-  export = codeceptjs;
+declare module 'codeceptjs' {
+  export default codeceptjs
+}
+
+declare module '@codeceptjs/helper' {
+  export default CodeceptJS.Helper
 }
 
-declare module "@codeceptjs/helper" {
-  export = CodeceptJS.Helper;
+declare module 'codeceptjs/effects' {
+  export const tryTo: TryTo
+  export const retryTo: RetryTo
+  export const hopeThat: HopeThat
 }