synchronized with docs

Author: Thanh Nguyen

docs/build/Mochawesome.js

@@ -1,4 +1,3 @@
-let addMochawesomeContext
 let currentTest
 let currentSuite
 
@@ -16,7 +15,8 @@ class Mochawesome extends Helper {
       disableScreenshots: false,
     }
 
-    addMochawesomeContext = require('mochawesome/addContext')
+    this._addContext = require('mochawesome/addContext')
+
     this._createConfig(config)
   }
 
@@ -44,28 +44,27 @@ class Mochawesome extends Helper {
     if (this.options.disableScreenshots) return
     let fileName
     // Get proper name if we are fail on hook
-    if (test.ctx.test.type === '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)}`
+      fileName = testToFileName(test)
     }
     if (this.options.uniqueScreenshotNames) {
-      const uuid = test.uuid || test.ctx.test.uuid
-      fileName = `${fileName.substring(0, 10)}_${uuid}`
+      fileName = testToFileName(test, { unique: true })
     }
     if (test._retries < 1 || test._retries === test.retryNum) {
       fileName = `${fileName}.failed.png`
-      return addMochawesomeContext(currentTest, fileName)
+      return this._addContext(currentTest, fileName)
     }
   }
 
   addMochawesomeContext(context) {
     if (currentTest === '') currentTest = { test: currentSuite.ctx.test }
-    return addMochawesomeContext(currentTest, context)
+    return this._addContext(currentTest, context)
   }
 }
 

docs/build/Playwright.js

@@ -3216,15 +3216,19 @@ class Playwright extends Helper {
     if (this.options.recordVideo && this.page && this.page.video()) {
       test.artifacts.video = saveVideoForPage(this.page, `${test.title}.failed`)
       for (const sessionName in this.sessionPages) {
-        test.artifacts[`video_${sessionName}`] = saveVideoForPage(this.sessionPages[sessionName], `${test.title}_${sessionName}.failed`)
+        if (sessionName === '') continue
+        test.artifacts[`video_${sessionName}`] = saveVideoForPage(this.sessionPages[sessionName], `${sessionName}_${test.title}.failed`)
       }
     }
 
     if (this.options.trace) {
       test.artifacts.trace = await saveTraceForContext(this.browserContext, `${test.title}.failed`)
       for (const sessionName in this.sessionPages) {
-        if (!this.sessionPages[sessionName].context) continue
-        test.artifacts[`trace_${sessionName}`] = await saveTraceForContext(this.sessionPages[sessionName].context, `${test.title}_${sessionName}.failed`)
+        if (sessionName === '') continue
+        const sessionPage = this.sessionPages[sessionName]
+        const sessionContext = sessionPage.context()
+        if (!sessionContext || !sessionContext.tracing) continue
+        test.artifacts[`trace_${sessionName}`] = await saveTraceForContext(sessionContext, `${sessionName}_${test.title}.failed`)
       }
     }
 
@@ -3238,7 +3242,8 @@ class Playwright extends Helper {
       if (this.options.keepVideoForPassedTests) {
         test.artifacts.video = saveVideoForPage(this.page, `${test.title}.passed`)
         for (const sessionName of Object.keys(this.sessionPages)) {
-          test.artifacts[`video_${sessionName}`] = saveVideoForPage(this.sessionPages[sessionName], `${test.title}_${sessionName}.passed`)
+          if (sessionName === '') continue
+          test.artifacts[`video_${sessionName}`] = saveVideoForPage(this.sessionPages[sessionName], `${sessionName}_${test.title}.passed`)
         }
       } else {
         this.page
@@ -3253,8 +3258,11 @@ class Playwright extends Helper {
         if (this.options.trace) {
           test.artifacts.trace = await saveTraceForContext(this.browserContext, `${test.title}.passed`)
           for (const sessionName in this.sessionPages) {
-            if (!this.sessionPages[sessionName].context) continue
-            test.artifacts[`trace_${sessionName}`] = await saveTraceForContext(this.sessionPages[sessionName].context, `${test.title}_${sessionName}.passed`)
+            if (sessionName === '') continue
+            const sessionPage = this.sessionPages[sessionName]
+            const sessionContext = sessionPage.context()
+            if (!sessionContext || !sessionContext.tracing) continue
+            test.artifacts[`trace_${sessionName}`] = await saveTraceForContext(sessionContext, `${sessionName}_${test.title}.passed`)
           }
         }
       } else {
@@ -5032,9 +5040,18 @@ function saveVideoForPage(page, name) {
 async function saveTraceForContext(context, name) {
   if (!context) return
   if (!context.tracing) return
-  const fileName = `${`${global.output_dir}${pathSeparator}trace${pathSeparator}${uuidv4()}_${clearString(name)}`.slice(0, 245)}.zip`
-  await context.tracing.stop({ path: fileName })
-  return fileName
+  try {
+    const fileName = `${`${global.output_dir}${pathSeparator}trace${pathSeparator}${uuidv4()}_${clearString(name)}`.slice(0, 245)}.zip`
+    await context.tracing.stop({ path: fileName })
+    return fileName
+  } catch (err) {
+    // Handle the case where tracing was not started or context is invalid
+    if (err.message && err.message.includes('Must start tracing before stopping')) {
+      // Tracing was never started on this context, silently skip
+      return null
+    }
+    throw err
+  }
 }
 
 async function highlightActiveElement(element) {

docs/changelog.md

@@ -7,6 +7,128 @@ layout: Section
 
 # Releases
 
+## 3.7.4
+
+❤️ Thanks all to those who contributed to make this release! ❤️
+
+🛩️ _Features_
+
+- **Test Suite Shuffling**: Randomize test execution order to discover test dependencies and improve test isolation ([#5051](https://github.com/codeceptjs/CodeceptJS/issues/5051)) - by **[NivYarmus](https://github.com/NivYarmus)**
+
+  ```bash
+  # Shuffle tests to find order-dependent failures using lodash.shuffle algorithm
+  npx codeceptjs run --shuffle
+
+  # Combined with grep and other options
+  npx codeceptjs run --shuffle --grep "@smoke" --steps
+  ```
+
+- **Enhanced Interactive Debugging**: Better logging for `I.grab*` methods in live interactive mode for clearer debugging output ([#4986](https://github.com/codeceptjs/CodeceptJS/issues/4986)) - by **[owenizedd](https://github.com/owenizedd)**
+
+  ```js
+  // Interactive pause() now shows detailed grab results with JSON formatting
+  I.amOnPage('/checkout')
+  pause()  // Interactive shell started
+  > I.grabTextFrom('.price')
+  Result $res= "Grabbed text: $29.99"  // Pretty-printed JSON output
+  > I.grabValueFrom('input[name="email"]')
+  {"value":"user@example.com"}  // Structured JSON response
+  ```
+
+  🐛 _Bug Fixes_
+
+- **Playwright Session Traces**: Fixed trace file naming convention and improved error handling for multi-session test scenarios ([#5073](https://github.com/codeceptjs/CodeceptJS/issues/5073)) - by **[julien-ft-64](https://github.com/julien-ft-64)** **[kobenguyent](https://github.com/kobenguyent)**
+
+  ```js
+  // Example outputs:
+  // - a1b2c3d4-e5f6_checkout_login_test.failed.zip
+  // - b2c3d4e5-f6g7_admin_dashboard_test.failed.zip
+  ```
+
+  _Trace files use UUID prefixes with `sessionName_testTitle.status.zip` format_
+
+- **Worker Data Injection**: Resolved proxy object serialization preventing data sharing between parallel test workers ([#5072](https://github.com/codeceptjs/CodeceptJS/issues/5072)) - by **[kobenguyent](https://github.com/kobenguyent)**
+
+  ```js
+  // Fixed: Complex objects can now be properly shared and injected between workers
+  // Bootstrap data sharing in codecept.conf.js:
+  exports.config = {
+    bootstrap() {
+      share({
+        userData: { id: 123, preferences: { theme: 'dark' } },
+        apiConfig: { baseUrl: 'https://api.test.com', timeout: 5000 },
+      })
+    },
+  }
+
+  // In tests across different workers:
+  const testData = inject()
+  console.log(testData.userData.preferences.theme) // 'dark' - deep nesting works
+  console.log(Object.keys(testData)) // ['userData', 'apiConfig'] - key enumeration works
+
+  // Dynamic sharing during test execution:
+  share({ newData: 'shared across workers' })
+  ```
+
+- **Hook Exit Codes**: Fixed improper exit codes when test hooks fail, ensuring CI/CD pipelines properly detect failures ([#5058](https://github.com/codeceptjs/CodeceptJS/issues/5058)) - by **[kobenguyent](https://github.com/kobenguyent)**
+
+  ```bash
+  # Before: Exit code 0 even when beforeEach/afterEach failed
+  # After: Exit code 1 when any hook fails, properly failing CI builds
+  ```
+
+- **TypeScript Effects Support**: Added complete TypeScript definitions for effects functionality ([#5027](https://github.com/codeceptjs/CodeceptJS/issues/5027)) - by **[kobenguyent](https://github.com/kobenguyent)**
+
+  ```typescript
+  // Import effects with full TypeScript type definitions
+  import { tryTo, retryTo, within } from 'codeceptjs/effects'
+
+  // tryTo returns Promise<boolean> for conditional actions
+  const success: boolean = await tryTo(async () => {
+    await I.see('Cookie banner')
+    await I.click('Accept')
+  })
+
+  // retryTo with typed parameters for reliability
+  await retryTo(() => {
+    I.click('Submit')
+    I.see('Success')
+  }, 3) // retry up to 3 times
+  ```
+
+  _Note: Replaces deprecated global plugins - import from 'codeceptjs/effects' module_
+
+- **Mochawesome Screenshot Uniqueness**: Fixed screenshot naming to prevent test failures from being overwritten when multiple tests run at the same time ([#4959](https://github.com/codeceptjs/CodeceptJS/issues/4959)) - by **[Lando1n](https://github.com/Lando1n)**
+
+  ```js
+  // Problem: When tests run in parallel, screenshots had identical names
+  // This caused later test screenshots to overwrite earlier ones
+
+  // Before: All failed tests saved as "screenshot.png"
+  // Result: Only the last failure screenshot was kept
+
+  // After: Each screenshot gets a unique name with timestamp
+  // Examples:
+  // - "login_test_1645123456.failed.png"
+  // - "checkout_test_1645123789.failed.png"
+  // - "profile_test_1645124012.failed.png"
+
+  // Configuration in codecept.conf.js:
+  helpers: {
+    Mochawesome: {
+      uniqueScreenshotNames: true // Enable unique naming
+    }
+  }
+  ```
+
+  _Ensures every failed test keeps its own screenshot for easier debugging_
+
+📖 _Documentation_
+
+- Fixed Docker build issues and improved container deployment process ([#4980](https://github.com/codeceptjs/CodeceptJS/issues/4980)) - by **[thomashohn](https://github.com/thomashohn)**
+- Updated dependency versions to maintain security and compatibility ([#4957](https://github.com/codeceptjs/CodeceptJS/issues/4957), [#4950](https://github.com/codeceptjs/CodeceptJS/issues/4950), [#4943](https://github.com/codeceptjs/CodeceptJS/issues/4943)) - by **[thomashohn](https://github.com/thomashohn)**
+- Fixed automatic documentation generation system for custom plugins ([#4973](https://github.com/codeceptjs/CodeceptJS/issues/4973)) - by **[Lando1n](https://github.com/Lando1n)**
+
 ## 3.7.3
 
 ❤️ Thanks all to those who contributed to make this release! ❤️
@@ -490,7 +612,6 @@ I.flushSoftAssertions() // Throws an error if any soft assertions have failed. T
 ```
 
 - feat(cli): print failed hooks ([#4476](https://github.com/codeceptjs/CodeceptJS/issues/4476)) - by **[kobenguyent](https://github.com/kobenguyent)**
-
   - run command
     ![Screenshot 2024-09-02 at 15 25 20](https://github.com/user-attachments/assets/625c6b54-03f6-41c6-9d0c-cd699582404a)
 
@@ -750,7 +871,6 @@ heal.addRecipe('reloadPageIfModalIsNotVisisble', {
 ```
 
 - **Breaking Change** **AI** features refactored. Read updated [AI guide](./ai):
-
   - **removed dependency on `openai`**
   - added support for **Azure OpenAI**, **Claude**, **Mistal**, or any AI via custom request function
   - `--ai` option added to explicitly enable AI features
@@ -761,7 +881,6 @@ heal.addRecipe('reloadPageIfModalIsNotVisisble', {
   - `OpenAI` helper renamed to `AI`
 
 - feat(puppeteer): network traffic manipulation. See [#4263](https://github.com/codeceptjs/CodeceptJS/issues/4263) by **[KobeNguyenT](https://github.com/KobeNguyenT)**
-
   - `startRecordingTraffic`
   - `grabRecordedNetworkTraffics`
   - `flushNetworkTraffics`
@@ -2099,7 +2218,6 @@ await I.seeTraffic({
 
 - **🪄 [AI Powered Test Automation](/ai)** - use OpenAI as a copilot for test automation. [#3713](https://github.com/codeceptjs/CodeceptJS/issues/3713) By **[davertmik](https://github.com/davertmik)**
   ![](https://user-images.githubusercontent.com/220264/250418764-c382709a-3ccb-4eb5-b6bc-538f3b3b3d35.png)
-
   - [AI guide](/ai) added
   - added support for OpenAI in `pause()`
   - added [`heal` plugin](/plugins#heal) for self-healing tests
@@ -2110,7 +2228,6 @@ await I.seeTraffic({
 ![](https://user-images.githubusercontent.com/220264/250415226-a7620418-56a4-4837-b790-b15e91e5d1f0.png)
 
 - **[Playwright]** Support for APIs in Playwright ([#3665](https://github.com/codeceptjs/CodeceptJS/issues/3665)) - by Egor Bodnar
-
   - `clearField` replaced to use new Playwright API
   - `blur` added
   - `focus` added
@@ -3521,9 +3638,7 @@ I.seeFile(fileName)
 ## 2.0.0
 
 - **[WebDriver]** **Breaking Change.** Updated to webdriverio v5. New helper **WebDriver** helper introduced.
-
   - **Upgrade plan**:
-
     1. Install latest webdriverio
 
     ```
@@ -3540,9 +3655,7 @@ I.seeFile(fileName)
 
 - **[Appium]** **Breaking Change.** Updated to use webdriverio v5 as well. See upgrade plan ↑
 - **[REST]** **Breaking Change.** Replaced `unirest` library with `axios`.
-
   - **Upgrade plan**:
-
     1. Refer to [axios API](https://github.com/axios/axios).
     2. If you were using `unirest` requests/responses in your tests change them to axios format.
 

docs/commands.md

@@ -47,6 +47,12 @@ Run single test with steps printed
 npx codeceptjs run github_test.js --steps
 ```
 
+Run test files in shuffled order
+
+```sh
+npx codeceptjs run --shuffle
+```
+
 Run single test in debug mode (see more in [debugging](#Debugging) section)
 
 ```sh

docs/examples.md

@@ -152,4 +152,7 @@ This is necessary if all integrations with TMS and CI/CD are already configured,
 * Tests are written in TS
 * CI/CD with Github Actions
 * Page Object Model is applied
-* ReportPortal Integration
+* ReportPortal Integration
+
+## How to
+* Create a plugin with TS [link](https://github.com/reutenkoivan/codeceptjs-plugins/tree/main/packages/html-snapshot-on-fail)