feat: support per-entry workingDir on playwrightChecks

A single bundled `checkly test`/`deploy` session can contain several
playwrightChecks, but they share one bundle root and one working directory, so
each self-contained Playwright project (its own package manager and pinned
@playwright/test) needs hand-written installCommand/testCommand shell surgery,
and the CLI resolves a single @playwright/test version for all of them.

Add an optional per-entry `workingDir` to PlaywrightCheck and playwrightChecks
config entries. When set, the bundler resolves that entry's Playwright version
from the working directory and stamps a per-entry working directory (plus a
working-dir-relative playwright config path) into the check payload, so one
session can carry projects on different Playwright versions without command
surgery.

Backward compatible: when `workingDir` is omitted, every computed value is
identical to today (defaults to the project directory).

Author: kiroushi

packages/cli/src/constructs/playwright-check.ts

@@ -94,6 +94,22 @@ export interface PlaywrightCheckProps extends Omit<RuntimeCheckProps, 'retryStra
    */
   include?: string | string[]
 
+  /**
+   * Working directory for this check's install and test commands, relative to
+   * the project (the directory that contains your Checkly config). Defaults to
+   * the project directory.
+   *
+   * Set this when a `playwrightChecks` entry points at a self-contained
+   * sub-project with its own package manager and pinned `@playwright/test`: the
+   * CLI then resolves that entry's Playwright version from this directory and
+   * the runner runs its commands from here. This lets one bundled session mix
+   * several fixtures on different Playwright versions without hand-written
+   * `installCommand`/`testCommand` shell surgery.
+   *
+   * @example "playwright-native/yarn-tests"
+   */
+  workingDir?: string
+
   /**
    * Name of the check group to assign this check to.
    * The group must exist in your project configuration.
@@ -150,6 +166,7 @@ export class PlaywrightCheck extends RuntimeCheck {
   pwProjects: string[]
   pwTags: string[]
   include: string[]
+  workingDir?: string
   engine?: Engine
   /** @deprecated Use {@link groupId} instead. Kept for compatibility with earlier versions. */
   groupName?: string
@@ -170,6 +187,7 @@ export class PlaywrightCheck extends RuntimeCheck {
     this.include = config.include
       ? (Array.isArray(config.include) ? config.include : [config.include])
       : []
+    this.workingDir = config.workingDir
     this.testCommand = config.testCommand
     this.groupName = config.groupName
     this.playwrightConfigPath = this.resolveContentFilePath(config.playwrightConfigPath)
@@ -491,7 +509,11 @@ export class PlaywrightCheck extends RuntimeCheck {
       relativePlaywrightConfigPath,
       workingDir,
       files,
-    } = await Session.getPlaywrightProjectBundler().bundle(this.playwrightConfigPath, this.include ?? [])
+    } = await Session.getPlaywrightProjectBundler().bundle(
+      this.playwrightConfigPath,
+      this.include ?? [],
+      this.workingDir,
+    )
 
     bundler.registerFiles(...files)
 

packages/cli/src/services/__tests__/playwright-project-bundler.spec.ts

@@ -29,16 +29,20 @@ function deferred<T> () {
 // Subclass that stubs the real bundling so we can count how many times it runs
 // and control its timing, without needing a full Session/filesystem setup.
 class CountingBundler extends PlaywrightProjectBundler {
-  calls: Array<{ config: string, include: string[] }> = []
+  calls: Array<{ config: string, include: string[], workingDir?: string }> = []
   #gate?: Promise<void>
 
   constructor (gate?: Promise<void>) {
     super()
     this.#gate = gate
   }
 
-  protected async bundleProject (config: string, include: string[]): Promise<PlaywrightProjectBundle> {
-    this.calls.push({ config, include })
+  protected async bundleProject (
+    config: string,
+    include: string[],
+    workingDir?: string,
+  ): Promise<PlaywrightProjectBundle> {
+    this.calls.push({ config, include, workingDir })
     if (this.#gate) {
       await this.#gate
     }
@@ -96,6 +100,25 @@ describe('PlaywrightProjectBundler cache', () => {
 
     expect(bundler.calls).toHaveLength(2)
   })
+
+  it('bundles separately for different working directories', async () => {
+    const bundler = new CountingBundler()
+
+    await bundler.bundle('pw.config.ts', ['a/**'], 'packages/foo')
+    await bundler.bundle('pw.config.ts', ['a/**'], 'packages/bar')
+
+    expect(bundler.calls).toHaveLength(2)
+  })
+
+  it('threads the working directory through and reuses the cache for the same key', async () => {
+    const bundler = new CountingBundler()
+
+    await bundler.bundle('pw.config.ts', ['a/**'], 'packages/foo')
+    await bundler.bundle('pw.config.ts', ['a/**'], 'packages/foo')
+
+    expect(bundler.calls).toHaveLength(1)
+    expect(bundler.calls[0].workingDir).toBe('packages/foo')
+  })
 })
 
 describe('getAutoIncludes()', () => {

packages/cli/src/services/checkly-config-loader.ts

@@ -35,7 +35,7 @@ export type PlaywrightSlimmedProp = Pick<PlaywrightCheckProps, 'name' | 'activat
   | 'muted' | 'shouldFail' | 'locations' | 'tags' | 'frequency' | 'environmentVariables'
   | 'alertChannels' | 'privateLocations' | 'alertEscalationPolicy'
   | 'pwProjects' | 'pwTags' | 'installCommand' | 'testCommand' | 'group' | 'groupName' | 'runParallel'
-  | 'engine'> & { logicalId: string, playwrightConfigPath?: string }
+  | 'engine' | 'workingDir'> & { logicalId: string, playwrightConfigPath?: string }
 
 export type ChecklyConfig = {
   /**

packages/cli/src/services/playwright-project-bundler.ts

@@ -31,29 +31,45 @@ export class PlaywrightProjectBundler {
   // config path and the serialized include patterns from colliding.
   #cache = new Map<string, Promise<PlaywrightProjectBundle>>()
 
-  async bundle (playwrightConfig: string, include: string[]): Promise<PlaywrightProjectBundle> {
-    const cacheKey = `${playwrightConfig}\0${JSON.stringify(include)}`
+  async bundle (playwrightConfig: string, include: string[], workingDir?: string): Promise<PlaywrightProjectBundle> {
+    const cacheKey = `${playwrightConfig}\0${JSON.stringify(include)}\0${workingDir ?? ''}`
     const cached = this.#cache.get(cacheKey)
     if (cached !== undefined) {
       return await cached
     }
-    const promise = this.bundleProject(playwrightConfig, include)
+    const promise = this.bundleProject(playwrightConfig, include, workingDir)
     this.#cache.set(cacheKey, promise)
     return await promise
   }
 
   // The actual bundling, separated from the cache wrapper above so it can be
   // overridden in tests. Not part of the public surface.
-  protected async bundleProject (playwrightConfig: string, include: string[]): Promise<PlaywrightProjectBundle> {
+  protected async bundleProject (
+    playwrightConfig: string,
+    include: string[],
+    workingDir?: string,
+  ): Promise<PlaywrightProjectBundle> {
     const dir = path.resolve(path.dirname(playwrightConfig))
     const filePath = path.resolve(dir, playwrightConfig)
 
+    // Per-entry working directory: where this check's install/test commands run,
+    // and where its @playwright/test version is resolved. `workingDir` is authored
+    // relative to the project context dir. When omitted it defaults to the context
+    // dir, so everything below collapses to the legacy single-working-dir behaviour.
+    // Setting it lets one bundled session carry several self-contained fixtures on
+    // different Playwright versions without hand-written install/test shell surgery.
+    const effectiveWorkingDir = workingDir
+      ? path.resolve(Session.contextPath!, workingDir)
+      : Session.contextPath!
+
     // No need of loading everything if there is no lockfile
     const pwtConfig = await Session.loadFile(filePath)
 
     const pwConfigParsed = new PlaywrightConfig(filePath, pwtConfig)
 
-    const playwrightVersion = await resolvePlaywrightVersion(dir)
+    // Resolve the version from the working dir when set (that's where the fixture
+    // declares/installs its own @playwright/test); otherwise from the config dir.
+    const playwrightVersion = await resolvePlaywrightVersion(workingDir ? effectiveWorkingDir : dir)
 
     const parser = Session.getPlaywrightParser()
     const { files, errors } = await parser.getFilesAndDependencies(pwConfigParsed)
@@ -104,8 +120,12 @@ export class PlaywrightProjectBundler {
     return {
       browsers: pwConfigParsed.getBrowsers(),
       playwrightVersion,
-      relativePlaywrightConfigPath: Session.contextRelativePosixPath(filePath),
-      workingDir: Session.relativePosixPath(Session.contextPath!),
+      // Both relative to the effective working dir: the runner runs the test
+      // command from `workingDir`, so the config path must resolve from there.
+      // With no per-entry workingDir these collapse to the legacy
+      // contextPath-relative values.
+      relativePlaywrightConfigPath: pathToPosix(path.relative(effectiveWorkingDir, filePath)),
+      workingDir: Session.relativePosixPath(effectiveWorkingDir),
       files,
     }
   }