docs: document fixture/page-object separation in browser tests (#10645)

## Summary

Document the agreed-upon architectural separation for browser test
fixtures:

- `fixtures/data/` — Static test data (mock API responses, workflow
JSONs, node definitions)
- `fixtures/components/` — Page object components (locators, user
interactions)
- `fixtures/helpers/` — Focused helper classes (domain-specific actions)
- `fixtures/utils/` — Pure utility functions (no page dependency)

## Changes

- **`browser_tests/AGENTS.md`** — Added architectural separation section
with clear rules for each directory
- **`browser_tests/fixtures/data/README.md`** (new) — Explains the data
directory purpose and what belongs here vs `assets/`

┆Issue is synchronized with this [Notion
page](https://www.notion.so/PR-10645-docs-document-fixture-page-object-separation-in-browser-tests-3316d73d365081febf52d165282c68f6)
by [Unito](https://www.unito.io)

---------

Co-authored-by: GitHub Action <action@github.com>

browser_tests/AGENTS.md

@@ -12,12 +12,13 @@ browser_tests/
 │   ├── ComfyMouse.ts     - Mouse interaction helper
 │   ├── VueNodeHelpers.ts - Vue Nodes 2.0 helpers
 │   ├── selectors.ts      - Centralized TestIds
-│   ├── components/       - Page object components
+│   ├── data/             - Static test data (mock API responses, workflow JSONs, node definitions)
+│   ├── components/       - Page object components (locators, user interactions)
 │   │   ├── ContextMenu.ts
 │   │   ├── SettingDialog.ts
 │   │   ├── SidebarTab.ts
 │   │   └── Topbar.ts
-│   ├── helpers/          - Focused helper classes
+│   ├── helpers/          - Focused helper classes (domain-specific actions)
 │   │   ├── CanvasHelper.ts
 │   │   ├── CommandHelper.ts
 │   │   ├── KeyboardHelper.ts
@@ -25,11 +26,18 @@ browser_tests/
 │   │   ├── SettingsHelper.ts
 │   │   ├── WorkflowHelper.ts
 │   │   └── ...
-│   └── utils/            - Utility functions
+│   └── utils/            - Pure utility functions (no page dependency)
 ├── helpers/          - Test-specific utilities
 └── tests/            - Test files (*.spec.ts)
 ```
 
+### Architectural Separation
+
+- **`fixtures/data/`** — Static test data only. Mock API responses, workflow JSONs, node definitions. No code, no imports from Playwright.
+- **`fixtures/components/`** — Page object components. Encapsulate locators and user interactions for a specific UI area.
+- **`fixtures/helpers/`** — Focused helper classes. Domain-specific actions that coordinate multiple page objects (e.g. canvas operations, workflow loading).
+- **`fixtures/utils/`** — Pure utility functions. No `Page` dependency; stateless helpers that can be used anywhere.
+
 ## Polling Assertions
 
 Prefer `expect.poll()` over `expect(async () => { ... }).toPass()` when the block contains a single async call with a single assertion. `expect.poll()` is more readable and gives better error messages (shows actual vs expected on failure).

eslint.config.ts

@@ -252,6 +252,22 @@ export default defineConfig([
       ]
     }
   },
+  // fixtures/data/ must contain only static data — no executable code or
+  // Playwright imports. This enforces the architectural separation documented
+  // in browser_tests/AGENTS.md.
+  {
+    files: ['browser_tests/fixtures/data/**/*.ts'],
+    rules: {
+      'no-restricted-syntax': [
+        'error',
+        {
+          selector: 'ImportDeclaration[source.value=/^@playwright/]',
+          message:
+            'fixtures/data/ must contain only static data. No Playwright imports allowed.'
+        }
+      ]
+    }
+  },
   {
     files: ['browser_tests/tests/**/*.test.ts'],
     rules: {