Migrate screenshot generator workflow to use wp-playground/cli

.github/scripts/wordpress-org-screenshots/blueprint.json

@@ -0,0 +1,55 @@
+{
+	"$schema": "https://playground.wordpress.net/blueprint-schema.json",
+	"preferredVersions": {
+		"php": "8.2",
+		"wp": "latest"
+	},
+	"phpExtensionBundles": [
+		"kitchen-sink"
+	],
+	"features": {
+		"networking": true
+	},
+	"constants": {
+		"WP_HTTP_BLOCK_EXTERNAL": "true"
+	},
+	"siteOptions": {
+		"blogname": "GatherPress",
+		"blogdescription": "Powering Communities with WordPress.",
+		"users_can_register": "1",
+		"permalink_structure": "/%postname%/"
+	},
+	"steps": [
+		{
+			"step": "defineWpConfigConsts",
+			"consts": {
+				"WP_DEBUG": false,
+				"WP_DEBUG_DISPLAY": false,
+				"DISABLE_WP_CRON": true,
+				"GATHERPRESS_ALPHA_VERSION": 1
+			}
+		},
+		{
+			"step": "login"
+		},
+		{
+			"step": "updateUserMeta",
+			"meta": {
+				"admin_color": "modern"
+			},
+			"userId": 1
+		},
+		{
+			"step": "activatePlugin",
+			"pluginName": "gatherpress",
+			"pluginPath": "/wordpress/wp-content/plugins/gatherpress"
+		},
+		{
+			"step": "importWxr",
+			"file": {
+				"resource": "url",
+				"url": "https://raw.githubusercontent.com/GatherPress/demo-data/main/GatherPress-demo-data-2024.xml"
+			}
+		}
+	]
+}

.github/scripts/wordpress-org-screenshots/playwright.config.ts

@@ -22,7 +22,10 @@ export default defineConfig({
 
 	expect: {
 		toHaveScreenshot: {
-			maxDiffPixelRatio: 0.1
+			// https://playwright.dev/docs/test-snapshots#maxdiffpixels
+			maxDiffPixelRatio: process.env.UPDATE_ALL_SNAPSHOTS ? 0 : 0.05,
+			// https://playwright.dev/docs/test-snapshots#stylepath
+			stylePath: './ui-adjustments.css'
 		},
 	},
 
@@ -34,35 +37,19 @@ export default defineConfig({
 		  name: "chromium",
 		  use: { ...devices["Desktop Chrome"] },
 		},
-
-		// {
-		// 	name: 'firefox',
-		// 	use: { ...devices['Desktop Firefox'] },
-		// },
-
-		// {
-		// 	name: 'webkit',
-		// 	use: { ...devices['Desktop Safari'] },
-		// },
-
-		/* Test against mobile viewports. */
-		// {
-		//   name: 'Mobile Chrome',
-		//   use: { ...devices['Pixel 5'] },
-		// },
-		// {
-		//   name: 'Mobile Safari',
-		//   use: { ...devices['iPhone 12'] },
-		// },
-
-		/* Test against branded browsers. */
-		// {
-		// 	name: 'Microsoft Edge',
-		// 	use: { ...devices['Desktop Edge'], channel: 'msedge' },
-		// },
-		// {
-		// 	name: 'Google Chrome',
-		// 	use: { ...devices['Desktop Chrome'], channel: 'chrome' },
-		// },
 	],
+	// Don't report slow test "files", as we will be running our tests in serial.
+	reportSlowTests: null,
+	use: {
+		...baseConfig.use,
+		baseURL: process.env.WP_BASE_URL || 'http://127.0.0.1:9400',
+	},
+	retries: 0,
+	webServer: {
+		...baseConfig.webServer,
+		command: 'npm run playground -- --blueprint=./localized_blueprint.json',
+		port: 9400,
+		// reuseExistingServer: !process.env.CI,
+		reuseExistingServer: true,
+	},
 });

.github/scripts/wordpress-org-screenshots/ui-adjustments.css

@@ -0,0 +1,12 @@
+/**
+    The content of this file is injected into the page within script tags,
+    rather than being included as a file.
+**/
+#adminmenuwrap {
+    /**
+        Stretch the dark grey background
+        behind the left main menu
+        over the full height of the page
+    **/
+    height: 10000px;
+}

.github/scripts/wordpress-org-screenshots/wporg.spec.ts

@@ -19,8 +19,10 @@ test.describe( 'Screenshots for the wordpress.org/plugins repository', () => {
     }
 
     test.beforeAll( async ( { requestUtils } ) => {
+
         // https://github.com/WordPress/gutenberg/blob/trunk/packages/e2e-test-utils-playwright/src/request-utils/site-settings.ts#L34-L35
 		language = ( await requestUtils.getSiteSettings() ).language;
+        console.log('language', language);
         local_code = ( 'en_US' === language ) ? '' : '-' + language.substring(0, 2);
 	} );
 

.github/workflows/compress-images.yml

@@ -0,0 +1,31 @@
+name: Compress Images
+on:
+  pull_request:
+    # Run Image Actions when JPG, JPEG, PNG or WebP files are added or changed.
+    # See https://help.github.com/en/actions/automating-your-workflow-with-github-actions/workflow-syntax-for-github-actions#onpushpull_requestpaths for reference.
+    paths:
+      - '**.jpg'
+      - '**.jpeg'
+      - '**.png'
+      - '**.webp'
+jobs:
+  build:
+    # Only run on Pull Requests within the same repository, and not from forks.
+    if: github.event.pull_request.head.repo.full_name == github.repository
+    name: calibreapp/image-actions
+    permissions: write-all
+    runs-on: ubuntu-latest
+    steps:
+
+      - name: Checkout Repo
+        uses: actions/checkout@v4
+
+      - name: Compress Images
+        uses: calibreapp/[email protected]
+        with:
+          # Configuration could be added
+          # https://github.com/marketplace/actions/image-actions#%EF%B8%8F-configuration
+          #
+          # The `GITHUB_TOKEN` is automatically generated by GitHub and scoped only to the repository that is currently running the action. By default, the action can’t update Pull Requests initiated from forked repositories.
+          # See https://docs.github.com/en/actions/reference/authentication-in-a-workflow and https://help.github.com/en/articles/virtual-environments-for-github-actions#token-permissions
+          githubToken: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/wordpress-org-screenshots.yml

@@ -1,7 +1,12 @@
 name: WordPress.org screenshot generation
 
 on:
+  pull_request: # JUST FOR TESTING !!
   workflow_dispatch:
+    inputs:
+      updateAllSnapshots:
+        description: 'Replace all existing images? (By default only changes will be updated.)'
+        default: false
 
 # Cancels all previous workflow runs.
 concurrency:
@@ -35,12 +40,6 @@ jobs:
     - name: Checkout
       uses: actions/checkout@v4
 
-    - name: Setup localised wp-env for ${{ matrix.locale }}
-      run: |
-        touch .wp-env.override.json
-        > .wp-env.override.json
-        echo "{ \"config\": { \"WPLANG\": \"${{ matrix.locale }}\" } }" >> .wp-env.override.json
-
     - uses: actions/cache@v4
       id: playwright-cache
       with:
@@ -85,31 +84,68 @@ jobs:
     - run: npx playwright install-deps
       if: steps.playwright-cache.outputs.cache-hit == 'true'
 
-    - name: Starting localised wp-env
+    - name: Prepare localized blueprint
+      # en_US should not get any additional steps added, as this will result in errors!
+      #
+      # All other locales need those two steps!
+      # The first downloads all lang-packs, while the second is important for
+      # "( await requestUtils.getSiteSettings() ).language;"
+      # which would otherwise return only "en_US". Learned that the hard way!
+      # Might be a bug in Playgrounds setSiteLanguage step or intended behaviour.
       run: |
-        npm run wp-env start --update
-
-        # Set language on the environment
-        # https://developer.wordpress.org/block-editor/reference-guides/packages/packages-env/#wp-env-run-container-command
-        # "wp-env run tests-cli "will run against localhost:8889
-        npm run wp-env run tests-cli wp language core install ${{ matrix.locale }}
-        npm run wp-env run tests-cli wp option update WPLANG ${{ matrix.locale }}
-
-        npm run wp-env run tests-cli wp language plugin install gatherpress ${{ matrix.locale }}
+        if [ ${{ matrix.locale }} == 'en_US' ]; then
+          cp .github/scripts/wordpress-org-screenshots/blueprint.json localized_blueprint.json
+        else
+          language_step='[
+            {
+              "step": "setSiteLanguage",
+              "language": "${{ matrix.locale }}"
+            },
+            {
+              "step": "wp-cli",
+              "command": "wp option update WPLANG ${{ matrix.locale }}"
+            }
+          ]'
+          echo "Use jq to append the site language step to the existing blueprint JSON file."
+          jq --argjson languageStep "$language_step" '.steps += $languageStep' .github/scripts/wordpress-org-screenshots/blueprint.json > localized_blueprint.json
+        fi
+
+    - name: Starting Playground
+      # Having this as a separate workflow step, should help making sure Playwright runs only, when this is DONE & READY.
+      #
+      # Because it seems to be a problem to "wait on webServer.command" https://github.com/microsoft/playwright/issues/11811
+      # & "it seems that globalSetup runs before webServer is started." https://github.com/microsoft/playwright/issues/11811#issuecomment-1040732201
+      # 
+      # The "&" is important to allow the next step to start!
+      run: |
+        npm run playground -- --blueprint=./localized_blueprint.json &
 
-    - name: Starting Playwright & Running the screenshot tests
+    - name: Running the screenshot tests
       id: screenshot-tests
       # Having set "continue-on-error:true" should help the workflow to pass (and get a green checkmark)
       # even if this step fails, what could happen because of intended changes or the addition of new locales.
       continue-on-error: true
+      if: ${{ ! github.event.inputs.updateAllSnapshots }}
+      env:
+        PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD: 1
+        WP_BASE_URL: 'http://127.0.0.1:9400/'
       run: |
-            npm run screenshots:wporg
+        DEBUG=pw:webserver \
+        npm run screenshots:wporg
 
-    - name: Starting Playwright again & Updating the Screenshots
+    - name: Updating the Screenshots
       # Using "continue-on-error:true" results in 'conclusion' being a success in any case, while the 'outcome' can differ.
       # And, as you already guessed, if: failure() looks at 'conclusion'.
-      if: ${{ steps.screenshot-tests.outcome == 'failure' }}
+      #
+      # Or the step is triggered directly, while the former step is skipped,
+      # when the updateAllSnapshots is trueish.
+      if: ${{ github.event.inputs.updateAllSnapshots || steps.screenshot-tests.outcome == 'failure' }}
+      env:
+        PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD: 1
+        WP_BASE_URL: 'http://127.0.0.1:9400/'
+        UPDATE_ALL_SNAPSHOTS: ${{ github.event.inputs.updateAllSnapshots }} 
       run: |
+        DEBUG=pw:webserver \
         npm run screenshots:wporg -- --update-snapshots
 
     - name: Commit updated screenshots
@@ -120,6 +156,7 @@ jobs:
         git checkout -b fix/wp-org-screenshots-${{ matrix.locale }}-${{ github.sha }}
         git config --local user.email "[email protected]"
         git config --local user.name "GitHub Action"
+        rm -f ./localized_blueprint.json
         git add -A
         git commit -m "Screenshots for ${{ matrix.locale }} updated!"
         git push origin fix/wp-org-screenshots-${{ matrix.locale }}-${{ github.sha }}
@@ -133,6 +170,6 @@ jobs:
       # Using Github CLI in Workflows
       # https://docs.github.com/en/actions/using-workflows/using-github-cli-in-workflows
       # https://cli.github.com/manual/gh_pr_create
-      run: gh pr create -B main -H fix/wp-org-screenshots-${{ matrix.locale }}-${{ github.sha }} --title 'Update ${{ matrix.locale }} screenshots for wordpress.org' --body 'Created by Github action'
+      run: gh pr create -B main -H fix/wp-org-screenshots-${{ matrix.locale }}-${{ github.sha }} --title 'Update ${{ matrix.locale }} screenshots for wordpress.org' --body 'Created with ❤️ by WordPress Playground, Playwright & Github action'
       env:
         GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

docs/contributor/screenshot-generator/README.md

@@ -0,0 +1,95 @@
+## Generate Screenshots using Playwright & Playground
+
+> Generating screenshots in multiple languages for the plugin and keeping them up to date with the development might become a time intensive task.
+
+GatherPress allows to generate screenshots for the plugin **automated & manually**, while sharing the same, [`wp-playground/cli`](https://github.com/WordPress/wordpress-playground/pull/1289) powered, setup. The started playground imports the [`GatherPress/demo-data`](https://github.com/GatherPress/demo-data) and sets some options to hide GatherPress' admin-notices.
+
+GatherPress uses Playwright for this, which is currently used as tool to do [end-to-end testing](../e2e-tests). Playwright has an advanced [screenshots API](https://playwright.dev/docs/screenshots), that allows to take screenshots for a full-page or an element only. Like for the e2e tests, it is configurable what browsers to use and what language to use in WordPress.
+
+GatherPress defined a set of screenshots to generate and get those generated
+
+- automatically using GitHub actions
+- (On every major and minor, but not on bug-fix, releases) *currently done manually via `workflow_dispatch`*
+- in all languages, with more than 90% of finished translations
+- with pixel-perfect consistency across releases & languages
+
+## Automated Screenshots
+
+...
+
+## Manually generating Screenshots
+
+### Install dependencies
+
+To generate screenshots you will have to install playwright using the following command:
+
+```bash
+npx playwright install --with-deps
+```
+
+> [!NOTE]
+> You also need to use Node.js 20 or later
+
+Install the dependencies to create the Playground instance, using the following command:
+
+```bash
+npm ci --legacy-peer-deps
+```
+
+### Run the Screenshot generator
+
+A call to `...` will automatically setup a `wp-playground/cli` powered WordPress instance.
+
+The testing is website is reachable at `http://127.0.0.1:9400`, the user is `admin` and the password is `password`. 
+
+_Choose one of the following options_
+
+1. For the _headless_ mode, use the following command:
+
+   ```bash
+   npm run screenshots:wporg
+   ```
+
+2. Run Playwright _visually_ (to run generating screenshots in isolation and change what's happening), use:
+
+   ```bash
+   npm run screenshots:wporg:ui
+   ```
+
+
+3. For _debug_ mode (which will open the browser along with Playwright Editor and allows you to record what's happening), use the following command:
+
+   ```bash
+   npm run screenshots:wporg:debug
+   ```
+
+   Run files that have *events.spec* in the file name.
+   ```bash
+   npm run screenshots:wporg:debug -- events.spec
+   ```
+
+   > [!NOTE]
+   > When writing a screenshot-generator(-test), using the debug mode is recommended since it will allow you to see the browser and the test in action.
+
+4. Run Tests independently _AND_ visually using the [Playwright VSCode extension](https://playwright.dev/docs/getting-started-vscode)
+
+    ...
+
+### Ressources
+
+#### Playwright & WordPress
+
+- [Playwright Screenshots API](https://playwright.dev/docs/screenshots)
+- [End-To-End Playwright test utils for WordPress](https://github.com/WordPress/gutenberg/blob/trunk/packages/e2e-test-utils-playwright/README.md)
+
+#### Screenshots for WordPress Plugins
+
+- 
+
+#### More about `wp-playground/cli`, as the environment
+
+Examples with great documentation:
+
+- [Playground CLI · WordPress/wordpress-playground#1289](https://github.com/WordPress/wordpress-playground/pull/1289)
+- [PoC: Run E2E tests with WP Playground · WordPress/gutenberg#62692](https://github.com/WordPress/gutenberg/pull/62692)
+- [Use WordPress Playground · swissspidy/wp-performance-action#173](https://github.com/swissspidy/wp-performance-action/pull/173)