From c66b99c499d07c208ddc7eab8aea37c93358f97c Mon Sep 17 00:00:00 2001
From: Colum Ferry <cferry09@gmail.com>
Date: Thu, 28 Nov 2024 13:37:08 +0000
Subject: [PATCH] docs(testing): add example of using Playwright's --project 
 argument with Nx (#29107)

## Current Behavior
Missing documentation on how to use Playwright's `--project` argument
with Nx.
Because Nx also has a `--project` argument, passing it to the command
like `nx e2e app --project=firefox` will result in the `--project` being
stripped from the command that is sent to Playwright.


## Expected Behavior
The fix is simple enough, change the command to be `nx e2e app --
--project=firefox` to ensure the argument is forwarded correctly to
Playwright.
Add some information to the Playwright plugin's overview documentation
to explain this.


## Related Issue(s)

Fixes #26965
---
 .../packages/playwright/documents/overview.md | 40 +++++++++++++++++++
 .../packages/playwright/playwright-plugin.md  | 40 +++++++++++++++++++
 2 files changed, 80 insertions(+)

diff --git a/docs/generated/packages/playwright/documents/overview.md b/docs/generated/packages/playwright/documents/overview.md
index 5511ad83ba419..961c8e1220dfb 100644
--- a/docs/generated/packages/playwright/documents/overview.md
+++ b/docs/generated/packages/playwright/documents/overview.md
@@ -159,6 +159,46 @@ nx e2e <your-app-name> --ui
 
 You can also use `--headed` flag to run Playwright where the browser can be seen without using the [Playwright UI](https://playwright.dev/docs/test-ui-mode)
 
+### Specifying a Project/Target Browser
+
+The default generated Playwright configuration will contain a `projects` property that contains a list of browsers to run the tests against.
+
+It should look similar to this:
+
+```ts
+export default defineConfig({
+  ...,
+  projects: [
+    {
+      name: "chromium",
+      use: { ...devices["Desktop Chrome"] },
+    },
+
+    {
+      name: "firefox",
+      use: { ...devices["Desktop Firefox"] },
+    },
+
+    {
+      name: "webkit",
+      use: { ...devices["Desktop Safari"] },
+    }
+  ]
+});
+```
+
+By default, Playwright will run tests against all browsers in the `projects` list.
+
+You can specify a specific browser to run the tests against by passing the `--project` flag to the `nx e2e` command.
+
+```shell
+nx e2e frontend-e2e -- --project=firefox
+```
+
+{% callout type="note" title="Argument Forwarding" %}
+As Nx also has a `--project` argument, you need to use `--` to forward the argument to the Playwright configuration.
+{% /callout %}
+
 ### Specifying a Base Url
 
 The `baseURL` property within the Playwright configuration can control where the tests visit by default.
diff --git a/docs/shared/packages/playwright/playwright-plugin.md b/docs/shared/packages/playwright/playwright-plugin.md
index 5511ad83ba419..961c8e1220dfb 100644
--- a/docs/shared/packages/playwright/playwright-plugin.md
+++ b/docs/shared/packages/playwright/playwright-plugin.md
@@ -159,6 +159,46 @@ nx e2e <your-app-name> --ui
 
 You can also use `--headed` flag to run Playwright where the browser can be seen without using the [Playwright UI](https://playwright.dev/docs/test-ui-mode)
 
+### Specifying a Project/Target Browser
+
+The default generated Playwright configuration will contain a `projects` property that contains a list of browsers to run the tests against.
+
+It should look similar to this:
+
+```ts
+export default defineConfig({
+  ...,
+  projects: [
+    {
+      name: "chromium",
+      use: { ...devices["Desktop Chrome"] },
+    },
+
+    {
+      name: "firefox",
+      use: { ...devices["Desktop Firefox"] },
+    },
+
+    {
+      name: "webkit",
+      use: { ...devices["Desktop Safari"] },
+    }
+  ]
+});
+```
+
+By default, Playwright will run tests against all browsers in the `projects` list.
+
+You can specify a specific browser to run the tests against by passing the `--project` flag to the `nx e2e` command.
+
+```shell
+nx e2e frontend-e2e -- --project=firefox
+```
+
+{% callout type="note" title="Argument Forwarding" %}
+As Nx also has a `--project` argument, you need to use `--` to forward the argument to the Playwright configuration.
+{% /callout %}
+
 ### Specifying a Base Url
 
 The `baseURL` property within the Playwright configuration can control where the tests visit by default.