feat(cli): embed private dependency tarballs into Playwright code bundles [RED-855]

packages/cli/src/ai-context/references/configure-playwright-checks.md

@@ -14,6 +14,7 @@
 - Use `installCommand` only when the default package-manager install command is not enough.
 - Checkly caches installed dependencies between runs, keyed off the lock file, `package.json` and `.npmrc` contents. To force a reinstall declaratively, set `caching.dependencyCache.version` (a string or a safe integer) at the top level of `checkly.config.ts` (not per check — one code bundle serves all Playwright Check Suites) and change its value whenever the cache should be invalidated; scheduled checks pick up the change on the next `checkly deploy`. Unset or empty-string values leave the cache key unchanged, so a dynamic value such as `version: process.env.DEPENDENCY_CACHE_VERSION` is safe when the variable is not always set. For a one-off reinstall during an ad-hoc run, use the `--refresh-cache` flag available on the run/test commands (`checkly test`, `checkly pw-test`, `checkly trigger`, `checkly checks run`) instead; the config value is the persistent knob that also applies to deployed, scheduled checks.
 - In Checkly CLI v8.0.0 and later, `include` patterns resolve relative to the Playwright config directory, not the project root. If `playwrightConfigPath` points to a subdirectory, adjust `include` globs. Example: `playwrightConfigPath: "./e2e/playwright.config.ts"` with a root fixture at `fixtures/data.json` needs `include: ["../fixtures/data.json"]`.
+- If dependencies come from a private registry that Checkly's infrastructure cannot reach (for example an intranet-only Nexus mirror), list them in `checks.embeddedPackages` in `checkly.config.ts`. Each entry is a package name (embeds every version found in the lockfile) or an exact `name@version` pin. List every unreachable package by name, including private packages that only appear as transitive dependencies of other private packages — dependencies of listed packages are not embedded automatically. The CLI resolves entries against the workspace-root lockfile (`pnpm-lock.yaml` or `package-lock.json`), reuses tarballs from local caches (its own, then npm's) or downloads them from the registry configured in `.npmrc`, verifies each against the lockfile's integrity hash, and ships them inside the code bundle at `.checkly/embedded-packages/*.tgz`, where the runner serves them through a local registry during install. Downloads are cached under the workspace root's `node_modules/.cache/checkly` (in a monorepo that is the repo root, not the member package; override with `CHECKLY_CACHE_DIR`; a per-user cache dir is the fallback when the project location isn't writable), so nothing lands in the project outside `node_modules`. CI setups that cache `node_modules` — or platforms that preserve `node_modules/.cache` — persist the tarballs automatically; otherwise persist `CHECKLY_CACHE_DIR` in CI to avoid re-downloading (note `npm ci` deletes `node_modules` wholesale, unlike incremental pnpm installs). The machine running `checkly deploy`/`test` needs registry access on a cold cache. Applies to Playwright Check Suites only, not browser or multistep checks.
 
 ## Install troubleshooting
 

packages/cli/src/commands/debug/parse-project.ts

@@ -149,6 +149,7 @@ export default class ParseProjectCommand extends Command {
         checklyConfigConstructs,
         playwrightConfigPath: checklyConfig.checks?.playwrightConfigPath,
         include: includeFlag.length ? includeFlag : checklyConfig.checks?.include,
+        embeddedPackages: checklyConfig.checks?.embeddedPackages,
         playwrightChecks: checklyConfig.checks?.playwrightChecks,
         loadPlaywrightChecksOnly: emulatePwTest,
         warnOnWebServerConfig: emulatePwTest && !(includeFlag.length > 0),

packages/cli/src/commands/deploy.ts

@@ -178,6 +178,7 @@ export default class Deploy extends AuthCommand {
       checklyConfigConstructs,
       playwrightConfigPath: checklyConfig.checks?.playwrightConfigPath,
       include: checklyConfig.checks?.include,
+      embeddedPackages: checklyConfig.checks?.embeddedPackages,
       playwrightChecks: checklyConfig.checks?.playwrightChecks,
     })
     const repoInfo = getGitInformation(project.repoUrl)

packages/cli/src/commands/pw-test.ts

@@ -214,6 +214,7 @@ export default class PwTestCommand extends AuthCommand {
       checklyConfigConstructs,
       playwrightConfigPath,
       include: includeFlag.length ? includeFlag : checklyConfig.checks?.include,
+      embeddedPackages: checklyConfig.checks?.embeddedPackages,
       playwrightChecks: [playwrightCheck],
       loadPlaywrightChecksOnly: true,
       warnOnWebServerConfig: !(includeFlag.length > 0),

packages/cli/src/commands/test.ts

@@ -206,6 +206,7 @@ export default class Test extends AuthCommand {
       checklyConfigConstructs,
       playwrightConfigPath: checklyConfig.checks?.playwrightConfigPath,
       include: checklyConfig.checks?.include,
+      embeddedPackages: checklyConfig.checks?.embeddedPackages,
       playwrightChecks: checklyConfig.checks?.playwrightChecks,
       checkFilter: check => {
         if (check instanceof HeartbeatMonitor) {

packages/cli/src/commands/validate.ts

@@ -62,6 +62,7 @@ export default class Validate extends AuthCommand {
       checklyConfigConstructs,
       playwrightConfigPath: checklyConfig.checks?.playwrightConfigPath,
       include: checklyConfig.checks?.include,
+      embeddedPackages: checklyConfig.checks?.embeddedPackages,
       playwrightChecks: checklyConfig.checks?.playwrightChecks,
     })
 

packages/cli/src/constructs/__tests__/fixtures/playwright-check/embedded-tarballs/.gitignore

@@ -0,0 +1,3 @@
+# The repo root ignores *.tgz for pnpm-pack output; these committed tarballs
+# are test fixtures for the embedded-packages feature.
+!*.tgz

packages/cli/src/constructs/__tests__/fixtures/playwright-check/embedded-tarballs/README.md

@@ -0,0 +1,34 @@
+# Embedded-packages tarball fixtures
+
+Tiny deterministic `.tgz` files used by the embedded-packages bundling tests
+in `playwright-check.spec.ts`. Their sha512 integrities are hardcoded in the
+`pnpm-lock.yaml` files of the `test-embedded-packages*` fixtures, so the
+tarball bytes and the lockfile entries must change together.
+
+To regenerate (and then update the `resolution.integrity` values the script
+prints into the fixture lockfiles):
+
+```python
+import tarfile, gzip, io, json, hashlib, base64
+
+def make_tgz(dest, name, version):
+    tar_buf = io.BytesIO()
+    with tarfile.open(fileobj=tar_buf, mode='w', format=tarfile.GNU_FORMAT) as tf:
+        pkg = json.dumps({"name": name, "version": version, "main": "index.js"}, indent=2).encode()
+        idx = f'module.exports = {json.dumps(name + "@" + version)}\n'.encode()
+        for path, data in [("package/package.json", pkg), ("package/index.js", idx)]:
+            info = tarfile.TarInfo(path)
+            info.size = len(data)
+            info.mtime = 0
+            info.mode = 0o644
+            tf.addfile(info, io.BytesIO(data))
+    gz_buf = io.BytesIO()
+    with gzip.GzipFile(fileobj=gz_buf, mode='wb', mtime=0) as gz:
+        gz.write(tar_buf.getvalue())
+    content = gz_buf.getvalue()
+    open(dest, 'wb').write(content)
+    print(dest, 'sha512-' + base64.b64encode(hashlib.sha512(content).digest()).decode())
+
+make_tgz("@acme+private-utils@1.2.3.tgz", "@acme/private-utils", "1.2.3")
+make_tgz("legacy-private-pkg@2.1.0.tgz", "legacy-private-pkg", "2.1.0")
+```

packages/cli/src/constructs/__tests__/fixtures/playwright-check/test-cases/test-embedded-packages-not-found/checkly.config.ts

@@ -0,0 +1,20 @@
+import { defineConfig } from 'checkly'
+
+const config = defineConfig({
+  projectName: 'Check Fixture',
+  logicalId: 'check-fixture',
+  checks: {
+    checkMatch: '**/*.check.ts',
+    ignoreDirectoriesMatch: [],
+    playwrightConfigPath: './playwright.config.ts',
+    embeddedPackages: ['no-such-package'],
+    playwrightChecks: [
+      {
+        logicalId: 'playwright-check-suite',
+        name: 'Playwright Check Suite',
+      }
+    ],
+  },
+})
+
+export default config

packages/cli/src/constructs/__tests__/fixtures/playwright-check/test-cases/test-embedded-packages-not-found/package.json

@@ -0,0 +1,7 @@
+{
+  "name": "playwright-bundle-test",
+  "version": "1.0.0",
+  "dependencies": {
+    "@playwright/test": "^1.55.1"
+  }
+}

packages/cli/src/constructs/__tests__/fixtures/playwright-check/test-cases/test-embedded-packages-not-found/playwright.config.ts

@@ -0,0 +1,6 @@
+import { defineConfig } from '@playwright/test'
+
+export default defineConfig({
+  testDir: './tests',
+  timeout: 30000,
+})

packages/cli/src/constructs/__tests__/fixtures/playwright-check/test-cases/test-embedded-packages-not-found/tests/example.spec.ts

@@ -0,0 +1,6 @@
+import { test, expect } from '@playwright/test'
+
+test('basic test', async ({ page }) => {
+  await page.goto('https://playwright.dev/')
+  expect(await page.title()).toContain('Playwright')
+})

packages/cli/src/constructs/__tests__/fixtures/playwright-check/test-cases/test-embedded-packages-subdir/checkly.config.ts

@@ -0,0 +1,20 @@
+import { defineConfig } from 'checkly'
+
+const config = defineConfig({
+  projectName: 'Check Fixture',
+  logicalId: 'check-fixture',
+  checks: {
+    checkMatch: '**/*.check.ts',
+    ignoreDirectoriesMatch: [],
+    playwrightConfigPath: './subdir/playwright.config.ts',
+    embeddedPackages: ['@acme/private-utils'],
+    playwrightChecks: [
+      {
+        logicalId: 'playwright-check-suite',
+        name: 'Playwright Check Suite',
+      }
+    ],
+  },
+})
+
+export default config

packages/cli/src/constructs/__tests__/fixtures/playwright-check/test-cases/test-embedded-packages-subdir/package.json

@@ -0,0 +1,7 @@
+{
+  "name": "playwright-bundle-test",
+  "version": "1.0.0",
+  "dependencies": {
+    "@playwright/test": "^1.55.1"
+  }
+}

packages/cli/src/constructs/__tests__/fixtures/playwright-check/test-cases/test-embedded-packages-subdir/subdir/playwright.config.ts

@@ -0,0 +1,6 @@
+import { defineConfig } from '@playwright/test'
+
+export default defineConfig({
+  testDir: './tests',
+  timeout: 30000,
+})

packages/cli/src/constructs/__tests__/fixtures/playwright-check/test-cases/test-embedded-packages-subdir/subdir/tests/example.spec.ts

@@ -0,0 +1,6 @@
+import { test, expect } from '@playwright/test'
+
+test('basic test', async ({ page }) => {
+  await page.goto('https://playwright.dev/')
+  expect(await page.title()).toContain('Playwright')
+})

packages/cli/src/constructs/__tests__/fixtures/playwright-check/test-cases/test-embedded-packages/checkly.config.ts

@@ -0,0 +1,20 @@
+import { defineConfig } from 'checkly'
+
+const config = defineConfig({
+  projectName: 'Check Fixture',
+  logicalId: 'check-fixture',
+  checks: {
+    checkMatch: '**/*.check.ts',
+    ignoreDirectoriesMatch: [],
+    playwrightConfigPath: './playwright.config.ts',
+    embeddedPackages: ['@acme/private-utils', 'legacy-private-pkg@2.1.0'],
+    playwrightChecks: [
+      {
+        logicalId: 'playwright-check-suite',
+        name: 'Playwright Check Suite',
+      }
+    ],
+  },
+})
+
+export default config

packages/cli/src/constructs/__tests__/fixtures/playwright-check/test-cases/test-embedded-packages/package.json

@@ -0,0 +1,7 @@
+{
+  "name": "playwright-bundle-test",
+  "version": "1.0.0",
+  "dependencies": {
+    "@playwright/test": "^1.55.1"
+  }
+}

packages/cli/src/constructs/__tests__/fixtures/playwright-check/test-cases/test-embedded-packages/playwright.config.ts

@@ -0,0 +1,6 @@
+import { defineConfig } from '@playwright/test'
+
+export default defineConfig({
+  testDir: './tests',
+  timeout: 30000,
+})

packages/cli/src/constructs/__tests__/fixtures/playwright-check/test-cases/test-embedded-packages/tests/example.spec.ts

@@ -0,0 +1,6 @@
+import { test, expect } from '@playwright/test'
+
+test('basic test', async ({ page }) => {
+  await page.goto('https://playwright.dev/')
+  expect(await page.title()).toContain('Playwright')
+})