CloudBeat Playwright Integration - Migration Guide

This guide describes the changes required to your Playwright project in order to support the latest CloudBeat execution engine. These updates enable individual test execution (instead of whole-spec only), nested folder support, improved result reporting, and greater overall flexibility.

---

1. Update @cloudbeat/playwright to v2.1.0

Update the package to the latest version using one of the following commands, depending on how it is installed in your project:

Regular dependency:

npm install --save @cloudbeat/playwright

Dev dependency:

npm install --save-dev @cloudbeat/playwright

After updating, verify your package.json reflects version 2.1.0 or higher. If you are using Git, make sure to commit the updated package-lock.json as well.

---

2. Update @playwright/test to v1.56.0 or Later (Optional)

This step is optional but strongly recommended if your test suite contains tests with Hebrew or other special characters in their names (e.g. accented letters, symbols, etc). Upgrading ensures more reliable test execution in those cases.

Dev dependency:

npm install --save-dev @playwright/test@1.56.0

---

3. Ensure Commands Run Successfully on an External Server

When a project is uploaded manually or synchronized from Git, CloudBeat executes the following two commands on its server:

npm ci
npx -y playwright test .spec.ts --list

Both commands must complete successfully in a clean, external environment. To verify this, make sure your project:

• Does not rely on any files that only exist on your local machine (note: dynamic imports inside test bodies are fine, as long as npx -y playwright test .spec.ts --list completes successfully - that command does not execute the tests themselves)

• Does not depend on packages from private registries or repositories (unless the server is configured to access them)

• Has a valid and complete package-lock.json committed to the repository (required by npm ci)

• Has all required environment variables documented, with safe defaults where possible

Test this locally by cloning your repo into a fresh directory and running both commands from scratch.

---

4. Remove Line Breaks from Test Titles

Test titles must not contain line breaks (\n). Tests with multi-line titles will not be executed correctly.

This issue most commonly occurs when using template literals (backtick strings) in JavaScript/TypeScript. Make sure all test titles are on a single line.

❌ Incorrect — contains a line break:

test(`user can log in
  with valid credentials`, async ({ page }) => {
  // ...
});

✅ Correct — single line:

test(`user can log in with valid credentials`, async ({ page }) => {
  // ...
});

Review your entire test suite for any test(...) or describe(...) blocks where the title string spans multiple lines, and flatten them.

---

5. Manually Added Cases Will Be Cleared on Project Re-upload/Re-Sync

⚠️ Important: Any test cases that were manually added to suites in CloudBeat will be removed when the project is re-uploaded/re-synced first time.

After completing the migration and re-uploading your project, make sure to re-add test cases to their respective suites.

---

Summary of Required Changes

#	Change	Required
1	Update @cloudbeat/playwright to 2.1.0+	✅ Yes
2	Update @playwright/test to 1.56.0+	⚠️ Optional (but highly recommended)
3	Ensure npm ci and --list commands succeed on a clean server	✅ Yes
4	Remove line breaks from all test titles	✅ Yes
5	Re-add manually added cases after re-upload/re-sync	⚠️ Informational