codeceptjs 4.0.0-rc.22 → 4.0.0-rc.24

package/docs/helpers/SoftExpectHelper.md

@@ -1,352 +0,0 @@
----
-permalink: /helpers/SoftExpectHelper
-editLink: false
-sidebar: auto
-title: SoftExpectHelper
----
-
-<!-- Generated by documentation.js. Update this documentation by updating the source code. -->
-
-## SoftAssertHelper
-
-**Extends ExpectHelper**
-
-SoftAssertHelper is a utility class for performing soft assertions.
-Unlike traditional assertions that stop the execution on failure,
-soft assertions allow the execution to continue and report all failures at the end.
-
-### Examples
-
-Zero-configuration when paired with other helpers like REST, Playwright:
-
-```js
-// inside codecept.conf.js
-{
-  helpers: {
-    Playwright: {...},
-    SoftExpectHelper: {},
-  }
-}
-```
-
-```js
-// in scenario
-I.softExpectEqual('a', 'b')
-I.flushSoftAssertions() // Throws an error if any soft assertions have failed. The error message contains all the accumulated failures.
-```
-
-## Methods
-
-### flushSoftAssertions
-
-Throws an error if any soft assertions have failed.
-The error message contains all the accumulated failures.
-
-- Throws **[Error][1]** If there are any soft assertion failures.
-
-### softAssert
-
-Performs a soft assertion by executing the provided assertion function.
-If the assertion fails, the error is caught and stored without halting the execution.
-
-#### Parameters
-
-- `assertionFn` **[Function][2]** The assertion function to execute.
-- `customErrorMsg` **[string][3]** A custom error message to display if the assertion fails.
-
-### softExpectAbove
-
-Softly asserts that the target data is above a specified value.
-
-#### Parameters
-
-- `targetData` **any** The data to check.
-- `aboveThan` **any** The value that the target data should be above.
-- `customErrorMsg` **[string][3]** A custom error message to display if the assertion fails.
-
-### softExpectBelow
-
-Softly asserts that the target data is below a specified value.
-
-#### Parameters
-
-- `targetData` **any** The data to check.
-- `belowThan` **any** The value that the target data should be below.
-- `customErrorMsg` **[string][3]** A custom error message to display if the assertion fails.
-
-### softExpectContain
-
-Softly asserts that a value contains the expected value.
-
-#### Parameters
-
-- `actualValue` **any** The actual value.
-- `expectedValueToContain` **any** The value that should be contained within the actual value.
-- `customErrorMsg` **[string][3]** A custom error message to display if the assertion fails.
-
-### softExpectDeepEqual
-
-Softly asserts that two values are deeply equal.
-
-#### Parameters
-
-- `actualValue` **any** The actual value.
-- `expectedValue` **any** The expected value.
-- `customErrorMsg` **[string][3]** A custom error message to display if the assertion fails.
-
-### softExpectDeepEqualExcluding
-
-Softly asserts that two objects are deeply equal, excluding specified fields.
-
-#### Parameters
-
-- `actualValue` **[Object][4]** The actual object.
-- `expectedValue` **[Object][4]** The expected object.
-- `fieldsToExclude` **[Array][5]<[string][3]>** The fields to exclude from the comparison.
-- `customErrorMsg` **[string][3]** A custom error message to display if the assertion fails.
-
-### softExpectDeepIncludeMembers
-
-Softly asserts that an array (superset) deeply includes all members of another array (set).
-
-#### Parameters
-
-- `superset` **[Array][5]** The array that should contain the expected members.
-- `set` **[Array][5]** The array with members that should be included.
-- `customErrorMsg` **[string][3]** A custom error message to display if the assertion fails.
-
-### softExpectDeepMembers
-
-Softly asserts that two arrays have deep equality, considering members in any order.
-
-#### Parameters
-
-- `actualValue` **[Array][5]** The actual array.
-- `expectedValue` **[Array][5]** The expected array.
-- `customErrorMsg` **[string][3]** A custom error message to display if the assertion fails.
-
-### softExpectEmpty
-
-Softly asserts that the target data is empty.
-
-#### Parameters
-
-- `targetData` **any** The data to check.
-- `customErrorMsg` **[string][3]** A custom error message to display if the assertion fails.
-
-### softExpectEndsWith
-
-Softly asserts that a value ends with the expected value.
-
-#### Parameters
-
-- `actualValue` **any** The actual value.
-- `expectedValueToEndWith` **any** The value that the actual value should end with.
-- `customErrorMsg` **[string][3]** A custom error message to display if the assertion fails.
-
-### softExpectEqual
-
-Softly asserts that two values are equal.
-
-#### Parameters
-
-- `actualValue` **any** The actual value.
-- `expectedValue` **any** The expected value.
-- `customErrorMsg` **[string][3]** A custom error message to display if the assertion fails.
-
-### softExpectEqualIgnoreCase
-
-Softly asserts that two values are equal, ignoring case.
-
-#### Parameters
-
-- `actualValue` **[string][3]** The actual string value.
-- `expectedValue` **[string][3]** The expected string value.
-- `customErrorMsg` **[string][3]** A custom error message to display if the assertion fails.
-
-### softExpectFalse
-
-Softly asserts that the target data is false.
-
-#### Parameters
-
-- `targetData` **any** The data to check.
-- `customErrorMsg` **[string][3]** A custom error message to display if the assertion fails.
-
-### softExpectHasAProperty
-
-Softly asserts that the target data has a property with the specified name.
-
-#### Parameters
-
-- `targetData` **any** The data to check.
-- `propertyName` **[string][3]** The property name to check for.
-- `customErrorMsg` **[string][3]** A custom error message to display if the assertion fails.
-
-### softExpectHasProperty
-
-Softly asserts that the target data has the specified property.
-
-#### Parameters
-
-- `targetData` **any** The data to check.
-- `propertyName` **[string][3]** The property name to check for.
-- `customErrorMsg` **[string][3]** A custom error message to display if the assertion
-  fails.
-
-### softExpectJsonSchema
-
-Softly asserts that the target data matches the given JSON schema.
-
-#### Parameters
-
-- `targetData` **any** The data to validate.
-- `jsonSchema` **[Object][4]** The JSON schema to validate against.
-- `customErrorMsg` **[string][3]** A custom error message to display if the assertion fails.
-
-### softExpectJsonSchemaUsingAJV
-
-Softly asserts that the target data matches the given JSON schema using AJV.
-
-#### Parameters
-
-- `targetData` **any** The data to validate.
-- `jsonSchema` **[Object][4]** The JSON schema to validate against.
-- `customErrorMsg` **[string][3]** A custom error message to display if the assertion fails.
-- `ajvOptions` **[Object][4]** Options to pass to AJV.
-
-### softExpectLengthAboveThan
-
-Softly asserts that the length of the target data is above a specified value.
-
-#### Parameters
-
-- `targetData` **any** The data to check.
-- `lengthAboveThan` **[number][6]** The length that the target data should be above.
-- `customErrorMsg` **[string][3]** A custom error message to display if the assertion fails.
-
-### softExpectLengthBelowThan
-
-Softly asserts that the length of the target data is below a specified value.
-
-#### Parameters
-
-- `targetData` **any** The data to check.
-- `lengthBelowThan` **[number][6]** The length that the target data should be below.
-- `customErrorMsg` **[string][3]** A custom error message to display if the assertion fails.
-
-### softExpectLengthOf
-
-Softly asserts that the target data has a specified length.
-
-#### Parameters
-
-- `targetData` **any** The data to check.
-- `length` **[number][6]** The expected length.
-- `customErrorMsg` **[string][3]** A custom error message to display if the assertion fails.
-
-### softExpectMatchesPattern
-
-Softly asserts that a value matches the expected pattern.
-
-#### Parameters
-
-- `actualValue` **any** The actual value.
-- `expectedPattern` **any** The pattern the value should match.
-- `customErrorMsg` **[string][3]** A custom error message to display if the assertion fails.
-
-### softExpectNotContain
-
-Softly asserts that a value does not contain the expected value.
-
-#### Parameters
-
-- `actualValue` **any** The actual value.
-- `expectedValueToNotContain` **any** The value that should not be contained within the actual value.
-- `customErrorMsg` **[string][3]** A custom error message to display if the assertion fails.
-
-### softExpectNotDeepEqual
-
-Softly asserts that two values are not deeply equal.
-
-#### Parameters
-
-- `actualValue` **any** The actual value.
-- `expectedValue` **any** The expected value.
-- `customErrorMsg` **[string][3]** A custom error message to display if the assertion fails.
-
-### softExpectNotEndsWith
-
-Softly asserts that a value does not end with the expected value.
-
-#### Parameters
-
-- `actualValue` **any** The actual value.
-- `expectedValueToNotEndWith` **any** The value that the actual value should not end with.
-- `customErrorMsg` **[string][3]** A custom error message to display if the assertion fails.
-
-### softExpectNotEqual
-
-Softly asserts that two values are not equal.
-
-#### Parameters
-
-- `actualValue` **any** The actual value.
-- `expectedValue` **any** The expected value.
-- `customErrorMsg` **[string][3]** A custom error message to display if the assertion fails.
-
-### softExpectNotStartsWith
-
-Softly asserts that a value does not start with the expected value.
-
-#### Parameters
-
-- `actualValue` **any** The actual value.
-- `expectedValueToNotStartWith` **any** The value that the actual value should not start with.
-- `customErrorMsg` **[string][3]** A custom error message to display if the assertion fails.
-
-### softExpectStartsWith
-
-Softly asserts that a value starts with the expected value.
-
-#### Parameters
-
-- `actualValue` **any** The actual value.
-- `expectedValueToStartWith` **any** The value that the actual value should start with.
-- `customErrorMsg` **[string][3]** A custom error message to display if the assertion fails.
-
-### softExpectToBeA
-
-Softly asserts that the target data is of a specific type.
-
-#### Parameters
-
-- `targetData` **any** The data to check.
-- `type` **[string][3]** The expected type (e.g., 'string', 'number').
-- `customErrorMsg` **[string][3]** A custom error message to display if the assertion fails.
-
-### softExpectToBeAn
-
-Softly asserts that the target data is of a specific type (alternative for articles).
-
-#### Parameters
-
-- `targetData` **any** The data to check.
-- `type` **[string][3]** The expected type (e.g., 'string', 'number').
-- `customErrorMsg` **[string][3]** A custom error message to display if the assertion fails.
-
-### softExpectTrue
-
-Softly asserts that the target data is true.
-
-#### Parameters
-
-- `targetData` **any** The data to check.
-- `customErrorMsg` **[string][3]** A custom error message to display if the assertion fails.
-
-[1]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Error
-[2]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function
-[3]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String
-[4]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object
-[5]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array
-[6]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number

package/docs/react.md

@@ -1,70 +0,0 @@
----
-permalink: /react
-title: Testing React Applications
----
-
-# Testing React Applications
-
-React applications require some additional love for end to end testing.
-At first, it is very hard to test an application which was never designed to be tested!
-This happens to many React application. While building components developers often forget to keep the element's semantic.
-
-Generated HTML code may often look like this:
-
-```js
-<div class="jss607 jss869 jss618 jss871 jss874 jss876" tabindex="0" role="tab" aria-selected="true" style="pointer-events: auto;">
-  <span class="jss877">
-    <span class="jss878">
-      <span class="jss879">Click Me!</span>
-    </span>
-  </span>
-<span class="jss610"></span></div>
-```
-
-It's quite common that clickable elements are not actual `a` or `button` elements. This way `I.click('Click Me!');` won't work, as well as `fillField('name', 'value)`. Finding a correct locator for such cases turns to be almost impossible.
-
-In this case test engineers have two options:
-
-1. Update JSX files to change output HTML and rebuild the application
-1. Test the application how it is.
-
-We recommend for long-running projects to go with the first option. The better you write your initial HTML the cleaner and less fragile will be your tests. Replace divs with correct HTML elements, add `data-` attributes, add labels, and names to input fields to make all CodeceptJS magic like clicking link by a text to work.
-
-However, if you can't update the code you can go to the second option. In this case, you should bind your locators to visible text on page and available semantic attribues. For instance, instead of using generated locator as this one:
-
-```
-//*[@id="document"]/div[2]/div/div[2]/div
-```
-
-use [Locator Builder](/locators#locator-builder) to make clean semantic locator:
-
-```js
-locate('[role=tab]').withText('Click Me!');
-```
-
-This way you can build very flexible and stable locators even on application never designed for testing.
-
-## Locators
-
-For React apps a special `react` locator is available. It allows to select an element by its component name, props and state.
-
-```js
-{ react: 'MyComponent' }
-{ react: 'Button', props: { title: 'Click Me' }}
-{ react: 'Button', state: { some: 'state' }}
-{ react: 'Input', state: 'valid'}
-```
-
-In WebDriver, Puppeteer, and Playwright you can use React locators in any method where locator is required:
-
-```js
-I.click({ react: 'Tab', props: { title: 'Click Me!' }});
-I.seeElement({ react: 't', props: { title: 'Clicked' }});
-```
-
-To find React element names and props in a tree use [React DevTools](https://chrome.google.com/webstore/detail/react-developer-tools/fmkadmapgofadopljbjfkapdkoienihi) extension.
-
-> Turn off minification for application builds otherwise component names will be uglified as well
-
-- With WebDriver and Puppeteer, React locators work via [resq](https://github.com/baruchvlz/resq) library, which handles React 16 and above.
-- With Playwright, React locators work via [Playwright React Locator](https://playwright.dev/docs/other-locators#react-locator).

package/lib/helper/Mochawesome.js

@@ -1,96 +0,0 @@
-let currentTest
-let currentSuite
-
-import Helper from '@codeceptjs/helper'
-import { createRequire } from 'module'
-import { clearString } from '../utils.js'
-import { testToFileName } from '../mocha/test.js'
-
-class Mochawesome extends Helper {
-  constructor(config) {
-    super(config)
-
-    // set defaults
-    this.options = {
-      uniqueScreenshotNames: false,
-      disableScreenshots: false,
-    }
-
-    // ESM-compatible require for CommonJS module
-    const require = createRequire(import.meta.url)
-    this._addContext = require('mochawesome/addContext')
-
-    this._createConfig(config)
-  }
-
-  _createConfig(config) {
-    // override defaults with config
-    Object.assign(this.options, config)
-  }
-
-  _beforeSuite(suite) {
-    currentSuite = suite
-    currentTest = ''
-  }
-
-  _before() {
-    if (currentSuite && currentSuite.ctx) {
-      currentTest = { test: currentSuite.ctx.currentTest }
-    }
-  }
-
-  _test(test) {
-    // If this is a retried test, we want to add context to the retried test
-    // but also potentially preserve context from the original test
-    const originalTest = test.retriedTest && test.retriedTest()
-    if (originalTest) {
-      // This is a retried test - use the retried test for context
-      currentTest = { test }
-
-      // Optionally copy context from original test if it exists
-      // Note: mochawesome context is stored in test.ctx, but we need to be careful
-      // not to break the mocha context structure
-    } else {
-      // Normal test (not a retry)
-      currentTest = { test }
-    }
-  }
-
-  _failed(test) {
-    if (this.options.disableScreenshots) return
-    let fileName
-    // Get proper name if we are fail on hook
-    if (test.ctx?.test?.type === 'hook') {
-      currentTest = { test: test.ctx.test }
-      // ignore retries if we are in hook
-      test._retries = -1
-      fileName = clearString(`${test.title}_${currentTest.test.title}`)
-    } else {
-      currentTest = { test }
-      fileName = testToFileName(test)
-    }
-    if (this.options.uniqueScreenshotNames) {
-      fileName = testToFileName(test, { unique: true })
-    }
-    if (test._retries < 1 || test._retries === test.retryNum) {
-      fileName = `${fileName}.failed.png`
-      return this._addContext(currentTest, fileName)
-    }
-  }
-
-  addMochawesomeContext(context) {
-    if (currentTest === '') currentTest = { test: currentSuite.ctx.test }
-
-    // For retried tests, make sure we're adding context to the current (retried) test
-    // not the original test
-    let targetTest = currentTest
-    if (currentTest.test && currentTest.test.retriedTest && currentTest.test.retriedTest()) {
-      // This test has been retried, make sure we're using the current test for context
-      targetTest = { test: currentTest.test }
-    }
-
-    return this._addContext(targetTest, context)
-  }
-}
-
-export default Mochawesome

package/lib/helper/extras/PlaywrightReactVueLocator.js

@@ -1,61 +0,0 @@
-import fs from 'fs'
-import { fileURLToPath } from 'url'
-
-let resqScript
-
-async function findReact(matcher, locator) {
-  const reactLocator = locator.locator || locator
-  const page = typeof matcher.page === 'function' ? matcher.page() : matcher
-
-  if (!resqScript) {
-    resqScript = fs.readFileSync(fileURLToPath(import.meta.resolve('resq'))).toString()
-  }
-  await page.evaluate(resqScript)
-  await page.evaluate(() => window.resq.waitToLoadReact())
-
-  const arrayHandle = await page.evaluateHandle(
-    ({ selector, props, state }) => {
-      let elements = window.resq.resq$$(selector)
-      if (Object.keys(props).length) elements = elements.byProps(props)
-      if (Object.keys(state).length) elements = elements.byState(state)
-      if (!elements.length) return []
-
-      let nodes = []
-      elements.forEach(element => {
-        let { node, isFragment } = element
-        if (!node) {
-          isFragment = true
-          node = element.children
-        }
-        if (isFragment) nodes = nodes.concat(node)
-        else nodes.push(node)
-      })
-      return [...nodes]
-    },
-    {
-      selector: reactLocator.react,
-      props: reactLocator.props || {},
-      state: reactLocator.state || {},
-    },
-  )
-
-  const properties = await arrayHandle.getProperties()
-  await arrayHandle.dispose()
-  const result = []
-  for (const property of properties.values()) {
-    const elementHandle = property.asElement()
-    if (elementHandle) result.push(elementHandle)
-  }
-  return result
-}
-
-async function findByPlaywrightLocator(matcher, locator) {
-  const pwLocator = locator.locator || locator
-  if (pwLocator && pwLocator.toString && pwLocator.toString().includes(process.env.testIdAttribute)) {
-    return matcher.getByTestId(pwLocator.pw.value.split('=')[1])
-  }
-  const pwValue = typeof pwLocator.pw === 'string' ? pwLocator.pw : pwLocator.pw
-  return matcher.locator(pwValue).all()
-}
-
-export { findReact, findByPlaywrightLocator }

package/lib/helper/extras/React.js

@@ -1,65 +0,0 @@
-import fs from 'fs'
-
-let resqScript
-
-export default async function findReact(matcher, locator) {
-  if (!resqScript) resqScript = fs.readFileSync(new URL('resq', import.meta.resolve('resq')).pathname)
-  await matcher.evaluate(resqScript.toString())
-  await matcher.evaluate(() => window.resq.waitToLoadReact())
-  const arrayHandle = await matcher.evaluateHandle(
-    obj => {
-      const { selector, props, state } = obj
-
-      let elements = window.resq.resq$$(selector)
-      if (Object.keys(props).length) {
-        elements = elements.byProps(props)
-      }
-      if (Object.keys(state).length) {
-        elements = elements.byState(state)
-      }
-
-      if (!elements.length) {
-        return []
-      }
-
-      // resq returns an array of HTMLElements if the React component is a fragment
-      // this avoids having nested arrays of nodes which the driver does not understand
-      // [[div, div], [div, div]] => [div, div, div, div]
-      let nodes = []
-
-      elements.forEach(element => {
-        let { node, isFragment } = element
-
-        if (!node) {
-          isFragment = true
-          node = element.children
-        }
-
-        if (isFragment) {
-          nodes = nodes.concat(node)
-        } else {
-          nodes.push(node)
-        }
-      })
-
-      return [...nodes]
-    },
-    {
-      selector: locator.react,
-      props: locator.props || {},
-      state: locator.state || {},
-    },
-  )
-
-  const properties = await arrayHandle.getProperties()
-  await arrayHandle.dispose()
-  const result = []
-  for (const property of properties.values()) {
-    const elementHandle = property.asElement()
-    if (elementHandle) {
-      result.push(elementHandle)
-    }
-  }
-
-  return result
-}