From 130720a691e005d1ee7d75b6663607531774ffe8 Mon Sep 17 00:00:00 2001 From: Didi Hoffmann Date: Thu, 2 Oct 2025 12:14:37 +0200 Subject: [PATCH 1/3] Adds the playwright command --- content/en/docs/measuring/playwright.md | 101 ++++++++++++++++++++ content/en/docs/measuring/usage-scenario.md | 3 +- 2 files changed, 103 insertions(+), 1 deletion(-) create mode 100644 content/en/docs/measuring/playwright.md diff --git a/content/en/docs/measuring/playwright.md b/content/en/docs/measuring/playwright.md new file mode 100644 index 0000000..3fb98bd --- /dev/null +++ b/content/en/docs/measuring/playwright.md @@ -0,0 +1,101 @@ +--- +title: "Playwright Command" +description: "Specification for using Playwright inside a usage_scenario.yml" +date: 2025-10-01 +weight: 420 +--- + +The Green Metrics Tool supports **Playwright** as a first-class command type in the `usage_scenario.yml`. +[Playwright](https://playwright.dev/) is a popular framework for end-to-end browser automation. With this integration, you can run browser-based user journeys directly inside your usage scenarios without maintaining a separate Playwright script file. + +--- + +## Defining Playwright Commands + +In addition to `console` commands, you can define steps of type `playwright`. + +Example: + +```yaml +flow: + - name: "Go to home page simple" + container: gcb-playwright + commands: + - type: playwright + command: await page.goto("https://green-coding.io") + - type: console + command: sleep 5 +``` + +- `type: playwright` + Defines a Playwright step instead of a shell command. +- `command:` **[str]** + A JavaScript/TypeScript snippet that is executed via Playwright inside the container. + +This allows you to inline browser interactions alongside other commands for fine-grained measurement. + +--- + +## Container Setup + +Playwright requires a container with the Playwright runtime installed. You can either install Playwright in your own container or use the [official Microsoft Playwright container](https://mcr.microsoft.com/en-us/product/playwright/about). + +Example: + +```yaml +services: + gcb-playwright: + image: mcr.microsoft.com/playwright:v1.55.0-noble +# volumes: +# - /tmp/.X11-unix:/tmp/.X11-unix # for debugging in non-headless mode +# environment: +# DISPLAY: ":0" # for debugging in non-headless mode + setup-commands: + # install playwright libraries + - command: mkdir /tmp/something + - command: cp -R /tmp/repo/. /tmp/something + - command: cd /tmp/something && npm init -y && npm install playwright # You can select the browser here if you only want one + shell: bash +``` + +--- + +## Running the Playwright IPC Listener + +Internally, Playwright commands are executed through an **inter-process communication (IPC) listener** that the Green Metrics Tool connects to. +You need to start this listener in your container before running Playwright steps. + +Example: + +```yaml +flow: + - name: "Start Playwright" + container: gcb-playwright + commands: + - type: console + command: node /tmp/something/playwright-ipc.js --browser firefox + note: Starting browser in background process with IPC + detach: true + - type: console + command: until [ -p "/tmp/playwright-ipc-ready" ]; do sleep 1; done && echo "Browser ready!" + shell: bash + note: Waiting for browser IPC listener to be ready +``` + +- The IPC script is available [here](https://raw.githubusercontent.com/green-coding-solutions/branch-magazine-energy-tests/refs/heads/main/playwright-ipc.js). +- The rendezvous file `/tmp/playwright-ipc-ready` is used as a readiness indicator. + +--- + +## Full Example + +You can find a complete `usage_scenario.yml` example here: +[Branch Magazine energy tests – usage_scenario_default_homepage.yml](https://github.com/green-coding-solutions/branch-magazine-energy-tests/blob/main/usage_scenario_default_homepage.yml) + +--- + + +## See also: +- [usage_scenario.yml Specification →](/docs/measuring/usage-scenario/) +- [Variables →](/docs/measuring/usage-scenario/#variables) +- [Branch Magazine Energy Tests](https://github.com/green-coding-solutions/branch-magazine-energy-tests/tree/main) diff --git a/content/en/docs/measuring/usage-scenario.md b/content/en/docs/measuring/usage-scenario.md index 942572d..ed1deb6 100644 --- a/content/en/docs/measuring/usage-scenario.md +++ b/content/en/docs/measuring/usage-scenario.md @@ -199,8 +199,9 @@ flow: + `name:` **[\.\s0-9a-zA-Z_\(\)-]+** An arbitrary name, that helps you distinguish later on where the load happend in the chart + `container:` **\[a-zA-Z0-9\]\[a-zA-Z0-9_.-\]+** The name of the container specified on `setup` which you want the run the flow + `commands:` **[list]** - - `type:` **[console]** (Only console currently supported) + - `type:` **[console|playwright]** + `console` will execute a shell command inside the container + + `playwright` will execute the playwright command in the container. See the [documentation](/docs/measuring/playwright/) for more details. - `command:` **[str]** + The command to be executed. If type is `console` then piping or moving to background is not supported. - `detach:` **[bool]** (optional, default: `false`) From 57c35b2914ee47883bdddc019bd37e93019a81fa Mon Sep 17 00:00:00 2001 From: Didi Hoffmann Date: Thu, 4 Dec 2025 18:03:53 +0100 Subject: [PATCH 2/3] update to new syntax --- content/en/docs/measuring/playwright.md | 102 +++++++++++++----------- 1 file changed, 54 insertions(+), 48 deletions(-) diff --git a/content/en/docs/measuring/playwright.md b/content/en/docs/measuring/playwright.md index 3fb98bd..a01b446 100644 --- a/content/en/docs/measuring/playwright.md +++ b/content/en/docs/measuring/playwright.md @@ -10,16 +10,23 @@ The Green Metrics Tool supports **Playwright** as a first-class command type in --- -## Defining Playwright Commands +## Simplified Setup with GMT Helper + +Getting started with Playwright is easy using the `!include-gmt-helper`. By including `gmt-playwright-v1.0.0.yml`, the Green Metrics Tool automatically: -In addition to `console` commands, you can define steps of type `playwright`. +1. Configures the Playwright service container (`gmt-playwright-nodejs`) with the official Microsoft Playwright image. +2. Installs all necessary Playwright libraries. +3. Starts the Playwright browser and an IPC listener in the background. -Example: +To get started, add the following to your `usage_scenario.yml`: ```yaml +!include-gmt-helper: gmt-playwright-v1.0.0.yml + +# Your flow can now use the gmt-playwright-nodejs container flow: - - name: "Go to home page simple" - container: gcb-playwright + - name: "Go to home page" + container: gmt-playwright-nodejs commands: - type: playwright command: await page.goto("https://green-coding.io") @@ -27,8 +34,18 @@ flow: command: sleep 5 ``` +This helper significantly simplifies your workflow by handling the setup for you. + +--- + +## Defining Playwright Commands + +As shown above, you can define steps of type `playwright` in your flow. + - `type: playwright` Defines a Playwright step instead of a shell command. +- `container: gmt-playwright-nodejs` + This must match the container provided by the GMT Playwright helper. - `command:` **[str]** A JavaScript/TypeScript snippet that is executed via Playwright inside the container. @@ -36,66 +53,55 @@ This allows you to inline browser interactions alongside other commands for fine --- -## Container Setup - -Playwright requires a container with the Playwright runtime installed. You can either install Playwright in your own container or use the [official Microsoft Playwright container](https://mcr.microsoft.com/en-us/product/playwright/about). +## Caching with a Reverse Proxy -Example: +For scenarios where you want to cache browser requests to minimize network variability, use the `gmt-playwright-with-cache-v1.0.0.yml` helper. It sets up an additional `squid` reverse proxy service and configures Playwright to use it. ```yaml -services: - gcb-playwright: - image: mcr.microsoft.com/playwright:v1.55.0-noble -# volumes: -# - /tmp/.X11-unix:/tmp/.X11-unix # for debugging in non-headless mode -# environment: -# DISPLAY: ":0" # for debugging in non-headless mode - setup-commands: - # install playwright libraries - - command: mkdir /tmp/something - - command: cp -R /tmp/repo/. /tmp/something - - command: cd /tmp/something && npm init -y && npm install playwright # You can select the browser here if you only want one - shell: bash +!include-gmt-helper: gmt-playwright-with-cache-v1.0.0.yml + +flow: + - name: "Go to home page with cache" + container: gmt-playwright-nodejs + commands: + - type: playwright + command: await page.goto("https://green-coding.io") ``` --- -## Running the Playwright IPC Listener - -Internally, Playwright commands are executed through an **inter-process communication (IPC) listener** that the Green Metrics Tool connects to. -You need to start this listener in your container before running Playwright steps. +## Full Example -Example: +Here is a complete `usage_scenario.yml` that measures the homepage of `green-coding.io`: ```yaml +!include-gmt-helper: gmt-playwright-v1.0.0.yml + +name: "Measure homepage of green-coding.io" +description: "A simple example that measures the energy consumption of a website's homepage." + flow: - - name: "Start Playwright" - container: gcb-playwright + - name: "Navigate to green-coding.io" + container: gmt-playwright-nodejs commands: + - type: playwright + command: await page.goto("https://green-coding.io") + note: "Navigate to the website" - type: console - command: node /tmp/something/playwright-ipc.js --browser firefox - note: Starting browser in background process with IPC - detach: true - - type: console - command: until [ -p "/tmp/playwright-ipc-ready" ]; do sleep 1; done && echo "Browser ready!" - shell: bash - note: Waiting for browser IPC listener to be ready -``` - -- The IPC script is available [here](https://raw.githubusercontent.com/green-coding-solutions/branch-magazine-energy-tests/refs/heads/main/playwright-ipc.js). -- The rendezvous file `/tmp/playwright-ipc-ready` is used as a readiness indicator. + command: sleep 10 + note: "Wait for 10 seconds to allow for idle load" ---- - -## Full Example - -You can find a complete `usage_scenario.yml` example here: -[Branch Magazine energy tests – usage_scenario_default_homepage.yml](https://github.com/green-coding-solutions/branch-magazine-energy-tests/blob/main/usage_scenario_default_homepage.yml) + - name: "Take a screenshot" + container: gmt-playwright-nodejs + commands: + - type: playwright + command: await page.screenshot({ path: '/tmp/repo/screenshot.png' }) + note: "Take a screenshot to verify the page loaded" +``` --- ## See also: - [usage_scenario.yml Specification →](/docs/measuring/usage-scenario/) -- [Variables →](/docs/measuring/usage-scenario/#variables) -- [Branch Magazine Energy Tests](https://github.com/green-coding-solutions/branch-magazine-energy-tests/tree/main) +- [Variables →](/docs/measuring/usage-scenario/#variables) From 7ace72f3cf2234ee35afe544acbf6ac406fe76ba Mon Sep 17 00:00:00 2001 From: Arne Tarara Date: Fri, 5 Dec 2025 12:35:57 +0100 Subject: [PATCH 3/3] Moved Playwright command to subpage of measuring websites --- .../en/docs/measuring/measuring-websites.md | 105 ++++++++++++++++- content/en/docs/measuring/playwright.md | 107 ------------------ 2 files changed, 103 insertions(+), 109 deletions(-) delete mode 100644 content/en/docs/measuring/playwright.md diff --git a/content/en/docs/measuring/measuring-websites.md b/content/en/docs/measuring/measuring-websites.md index f9b4c50..ef9374f 100644 --- a/content/en/docs/measuring/measuring-websites.md +++ b/content/en/docs/measuring/measuring-websites.md @@ -15,7 +15,7 @@ To isolate this as best as possible GMT orchestrates a reverse proxy, warms up t **Warning:** Measuring websites is very tricky! GMT shaves off some of the caveats by using reverse proxys and cache pre-loading to make results more reliable. Since measurement load times are in milliseconds range you must have [Metric Providers]({{< relref "/docs/measuring/metric-providers/" >}}) with very high *sampling_rates* connected. **2ms** is a good value. Also website measurements are really only realiable in a [controlled cluster]({{< relref "/docs/cluster/" >}}) with [accuracy control]({{< relref "/docs/cluster/accuracy-control" >}}). -#### Quick website measuring +## Quick website measuring Since measuring websites is so common GMT comes with a quick measurement function for that. @@ -27,8 +27,109 @@ It will download the needed containers, setup them up and run the measurement. O Bonus tip: If you apply `--quick` to the `run-template.sh` call the measurement is quicker for debugging purposes. However results will be not as reliable. Use only for debugging! -#### Trying out our hosted service +## Trying out our hosted service We operate [website-tester.green-coding.io](https://website-tester.green-coding.io) as a simple demo vertical that uses the underlying [Green Metrics Tool Cluster Hosted Service →]({{< relref "/docs/measuring/measuring-service" >}}). Check it out if you do not feel like installing the GMT and just want to get carbon and energy info on a single page. + +## Crafting your own flows with Playwright commands + +The Green Metrics Tool supports **Playwright** as a first-class command type in the `usage_scenario.yml`. +[Playwright](https://playwright.dev/) is a popular framework for end-to-end browser automation. With this integration, you can run browser-based user journeys directly inside your usage scenarios without maintaining a separate Playwright script file. + +--- + +### Simplified Setup with GMT Helper + +Getting started with Playwright is easy using the `!include-gmt-helper`. By including `gmt-playwright-v1.0.0.yml`, the Green Metrics Tool automatically: + +1. Configures the Playwright service container (`gmt-playwright-nodejs`) with the official Microsoft Playwright image. +2. Installs all necessary Playwright libraries. +3. Starts the Playwright browser and an IPC listener in the background. + +To get started, add the following to your `usage_scenario.yml`: + +```yaml +!include-gmt-helper: gmt-playwright-v1.0.0.yml + +# Your flow can now use the gmt-playwright-nodejs container +flow: + - name: "Go to home page" + container: gmt-playwright-nodejs + commands: + - type: playwright + command: await page.goto("https://green-coding.io") + - type: console + command: sleep 5 +``` + +This helper significantly simplifies your workflow by handling the setup for you. + +--- + +### Defining Playwright Commands + +As shown above, you can define steps of type `playwright` in your flow. + +- `type: playwright` + Defines a Playwright step instead of a shell command. +- `container: gmt-playwright-nodejs` + This must match the container provided by the GMT Playwright helper. +- `command:` **[str]** + A JavaScript/TypeScript snippet that is executed via Playwright inside the container. + +This allows you to inline browser interactions alongside other commands for fine-grained measurement. + +--- + +### Caching with a Reverse Proxy + +For scenarios where you want to cache browser requests to minimize network variability, use the `gmt-playwright-with-cache-v1.0.0.yml` helper. It sets up an additional `squid` reverse proxy service and configures Playwright to use it. + +```yaml +!include-gmt-helper: gmt-playwright-with-cache-v1.0.0.yml + +flow: + - name: "Go to home page with cache" + container: gmt-playwright-nodejs + commands: + - type: playwright + command: await page.goto("https://green-coding.io") +``` + +--- + +### Full Example + +Here is a complete `usage_scenario.yml` that measures the homepage of `green-coding.io`: + +```yaml +!include-gmt-helper: gmt-playwright-v1.0.0.yml + +name: "Measure homepage of green-coding.io" +description: "A simple example that measures the energy consumption of a website's homepage." + +flow: + - name: "Navigate to green-coding.io" + container: gmt-playwright-nodejs + commands: + - type: playwright + command: await page.goto("https://green-coding.io") + note: "Navigate to the website" + - type: console + command: sleep 10 + note: "Wait for 10 seconds to allow for idle load" + + - name: "Take a screenshot" + container: gmt-playwright-nodejs + commands: + - type: playwright + command: await page.screenshot({ path: '/tmp/repo/screenshot.png' }) + note: "Take a screenshot to verify the page loaded" +``` + +--- + +- [usage_scenario.yml Specification →]({{< relref "/docs/measuring/usage-scenario/" >}}) +- [Variables →]({{< relref "/docs/measuring/usage-scenario/#variables" >}}) diff --git a/content/en/docs/measuring/playwright.md b/content/en/docs/measuring/playwright.md deleted file mode 100644 index a01b446..0000000 --- a/content/en/docs/measuring/playwright.md +++ /dev/null @@ -1,107 +0,0 @@ ---- -title: "Playwright Command" -description: "Specification for using Playwright inside a usage_scenario.yml" -date: 2025-10-01 -weight: 420 ---- - -The Green Metrics Tool supports **Playwright** as a first-class command type in the `usage_scenario.yml`. -[Playwright](https://playwright.dev/) is a popular framework for end-to-end browser automation. With this integration, you can run browser-based user journeys directly inside your usage scenarios without maintaining a separate Playwright script file. - ---- - -## Simplified Setup with GMT Helper - -Getting started with Playwright is easy using the `!include-gmt-helper`. By including `gmt-playwright-v1.0.0.yml`, the Green Metrics Tool automatically: - -1. Configures the Playwright service container (`gmt-playwright-nodejs`) with the official Microsoft Playwright image. -2. Installs all necessary Playwright libraries. -3. Starts the Playwright browser and an IPC listener in the background. - -To get started, add the following to your `usage_scenario.yml`: - -```yaml -!include-gmt-helper: gmt-playwright-v1.0.0.yml - -# Your flow can now use the gmt-playwright-nodejs container -flow: - - name: "Go to home page" - container: gmt-playwright-nodejs - commands: - - type: playwright - command: await page.goto("https://green-coding.io") - - type: console - command: sleep 5 -``` - -This helper significantly simplifies your workflow by handling the setup for you. - ---- - -## Defining Playwright Commands - -As shown above, you can define steps of type `playwright` in your flow. - -- `type: playwright` - Defines a Playwright step instead of a shell command. -- `container: gmt-playwright-nodejs` - This must match the container provided by the GMT Playwright helper. -- `command:` **[str]** - A JavaScript/TypeScript snippet that is executed via Playwright inside the container. - -This allows you to inline browser interactions alongside other commands for fine-grained measurement. - ---- - -## Caching with a Reverse Proxy - -For scenarios where you want to cache browser requests to minimize network variability, use the `gmt-playwright-with-cache-v1.0.0.yml` helper. It sets up an additional `squid` reverse proxy service and configures Playwright to use it. - -```yaml -!include-gmt-helper: gmt-playwright-with-cache-v1.0.0.yml - -flow: - - name: "Go to home page with cache" - container: gmt-playwright-nodejs - commands: - - type: playwright - command: await page.goto("https://green-coding.io") -``` - ---- - -## Full Example - -Here is a complete `usage_scenario.yml` that measures the homepage of `green-coding.io`: - -```yaml -!include-gmt-helper: gmt-playwright-v1.0.0.yml - -name: "Measure homepage of green-coding.io" -description: "A simple example that measures the energy consumption of a website's homepage." - -flow: - - name: "Navigate to green-coding.io" - container: gmt-playwright-nodejs - commands: - - type: playwright - command: await page.goto("https://green-coding.io") - note: "Navigate to the website" - - type: console - command: sleep 10 - note: "Wait for 10 seconds to allow for idle load" - - - name: "Take a screenshot" - container: gmt-playwright-nodejs - commands: - - type: playwright - command: await page.screenshot({ path: '/tmp/repo/screenshot.png' }) - note: "Take a screenshot to verify the page loaded" -``` - ---- - - -## See also: -- [usage_scenario.yml Specification →](/docs/measuring/usage-scenario/) -- [Variables →](/docs/measuring/usage-scenario/#variables)