Document setting Docker image version dynamically (JS)

[karlhorky]

The Docker container approach hardcodes the Playwright version in a new place in the codebase - the GitHub Actions workflow files - requiring effort or automation to keep the Playwright versions in sync in both package.json and the GitHub Actions workflow files. There is a high chance of these versions getting out of sync as Playwright is upgraded.

The container image version can be kept up to date with the Playwright version in package.json with configuring a previous GitHub Actions job, as documented in the following resources:

• https://github.com/karlhorky/repro-dynamic-playwright-container-image
• https://github.com/karlhorky/playwright-tricks#sync-playwright-version-from-packagejson-to-github-actions-container-image
• [Question]: How to cache on github actions? #7249 (comment)

Alternatives Considered

1. This could be an addition to the existing "Via Containers" section, with examples for all languages Node.js, Python, Java, .NET
2. This new workflow could become the default suggested "Via Containers" workflow for GitHub Actions
3. A separate GitHub Actions workflow to edit the versions in the workflow files and commit to Git (downsides: more PR noise and greater required GitHub permissions)

[mxschmitt]

I think we should read it from the lockfile instead - because ^1.30 could also end up in v1.55.0 - wdyt?

[karlhorky]

Yeah, I considered that: downside would be complexity - since there are a lot of people not on npm, should be provided for every lockfile format (npm-lock.json, yarn.lock, pnpm-lock.yaml, bun.lock).

I was also looking into possible CLI commands (eg. npm, yarn, pnpm, bun commands) or trusted npm packages which would make this simple, but I didn't see something simple and unified in half an hour of research.

That's why I ended up with the extra text in the paragraph:

if you install an exact version of Playwright, then it can be retrieved from package.json

But exact versions are pretty uncommon in package.json files, so maybe worth doing something about it.

---

If it's worth it, I could try writing some commands / a small script in this direction.

[karlhorky]

Another (more expensive) alternative would be to install Playwright from the package.json + lockfile using the detected package manager (minimal command branching here) and either:

1. Retrieve the version using npm list, yarn list, pnpm list, etc
2. Retrieve the version from node_modules/@playwright/test/package.json (downside: this wouldn't work for package managers which don't use node_modules)

[Fannon]

For me this doesn't work, because I have a ^ in my package.json

  Warning: Docker pull failed with exit code 1, back off 5.126 seconds before retry.
  /usr/bin/docker pull mcr.microsoft.com/playwright:v^1.56.0-noble
  invalid reference format

[karlhorky]

Yeah, that's the situation that I described above:

But exact versions are pretty uncommon in package.json files, so maybe worth doing something about it.

So probably worth it to either:

1. Write some commands / a small script to read the version from all common lockfile formats
2. Install @playwright/test using package manager + retrieve version using package manager commands like npm list

@mxschmitt what do you think?

[karlhorky]

For this item:

1. Write some commands / a small script to read the version from all common lockfile formats

It looks like we may be able to use lockparse from @43081j, ("tiny zero-dependency lockfile parser for npm, Yarn, pnpm, and Bun"):

import { parse } from 'lockparse';
import { readFile } from 'node:fs/promises';

const lockfileContent = await readFile('./pnpm-lock.yaml', 'utf-8');
const packageJson = JSON.parse(await readFile('./package.json', 'utf-8'));
const lockfile = await parse(lockfileContent, 'pnpm', packageJson);

console.log(lockfile);

Output:

{
  type: 'pnpm',
  packages: [
    { /* ... */ },
    // ...
  ],
  root: {
    name: 'root',
    version: '',
    dependencies: [
      // ...
    ],
    devDependencies: [
      {
        name: '@playwright/test',
        version: '1.56.1',
        dependencies: [
          {
            name: 'playwright',
            version: '1.56.1',
            dependencies: [Array],
            devDependencies: [],
            optionalDependencies: [Array],
            peerDependencies: []
          }
        ],
        devDependencies: [],
        optionalDependencies: [],
        peerDependencies: []
      },
      // ...
    ],
    optionalDependencies: [],
    peerDependencies: []
  }
}

Or something with higher usage numbers (118k downloads / week as of writing):

• https://www.npmjs.com/package/snyk-nodejs-lockfile-parser

[pavelfeldman]

What are you trying to solve? Could you file an issue instead?

[karlhorky]

@pavelfeldman ah sorry, forgot to copy the problem description to the PR, I've added it to the top of the PR description now

Main idea is: the version in the workflow yaml files gets easily forgotten and outdated as Playwright versions in package.json get updated.

Keeping package.json and/or lockfiles (see discussion with @mxschmitt above) as the source of truth is helpful to resolve this.

[karlhorky]

@pavelfeldman @mxschmitt I opened a new PR (including companion issue) - found what seems to be a pretty elegant solution:

• PR: Document dynamic CI container image tag #39995