octoperf-real-browser-probe

# OctoPerf — Real-browser probe alongside JMeter load

## The pattern

JMeter HTTP virtual users are great for server-side metrics (response
time, throughput, error rate) but they don't reflect what a real user
*perceives*: page load, JS execution, rendering, layout shifts, Core
Web Vitals. A **real-browser probe** is a single Playwright VU that
runs the same user journey through an actual Chromium during the load
test — measuring UX while the JMeter pool keeps the server busy.

Commercial equivalents (the LLM will recognise these terms): NeoLoad
*RealBrowser User*, LoadRunner *TruClient*, Gatling *Browser User*,
k6 *browser* module, BlazeMeter *Real Browser Users*. The pattern is
also known as **synthetic browser probe** or **end-user experience
monitoring during load test**.

## When this applies

The user has:

- A working OctoPerf JMeter Virtual User (validated clean) that they
  want to load-test.
- The need for **user-perceived metrics** during the test, not just
  server-side HTTP metrics — typically because the front-end is
  JS-heavy (SPA, React/Vue/Angular) and HTTP timings miss the
  client-side render cost.
- Optionally, an SLA framed around browser metrics (e.g. "TTFB < 200 ms
  AND LCP < 2.5 s under 50 concurrent users").

If the user just wants HTTP load (no UX measurement) → stick to
`run_scenario` on the JMeter VU. If the user wants *only* browser
testing without a load backdrop → just create the Playwright VU
without the JMeter one.

## Steps

### 1. Decide: direct translation vs codegen capture

Read the source JMeter VU's action tree:

```
mcp__octoperf__get_virtual_user(virtualUserId)
```

Classify the flow:

| Flow shape                                                                   | Path                                                                       |
|------------------------------------------------------------------------------|----------------------------------------------------------------------------|
| Linear navigation + simple forms (≤ 20 HTTP actions)                         | Step 2 (direct translation)                                                |
| Auth widgets, OAuth popups, file uploads, iframe-heavy SPA, JS-driven canvas | Step 2-bis (`playwright codegen`)                                          |
| Mixed: most simple, a few complex steps                                      | Direct translation, leave `// TODO codegen` markers for the complex blocks |

Direct translation is fast (no manual capture) but **brittle on
dynamic UIs**: a single-page app that doesn't change the URL between
clicks will defeat `page.goto(...)`. When in doubt, codegen.

### 2. Direct translation (JMeter → Playwright spec)

Walk the JMeter action tree and emit one Playwright statement per
action. Translation rules:

| JMeter element                                | Playwright equivalent                                                      |
|-----------------------------------------------|----------------------------------------------------------------------------|
| `HttpRequestAction` GET                       | `await page.goto(url)`                                                     |
| `HttpRequestAction` POST (form-urlencoded)    | `page.fill('input[name="x"]', value)` + `page.click('input[type=submit]')` |
| `HttpRequestAction` POST (JSON / multipart)   | `page.evaluate(() => fetch(...))` OR rebuild via real DOM interactions     |
| `${variable}` (JMeter CSV/Counter/Random)     | JS variable, `process.env.X`, or Playwright fixture                        |
| `ResponseAssertion` (BODY contains/not)       | `await expect(page.locator('body')).toContainText(...)`                    |
| `ThinktimeConstant`                           | `await page.waitForTimeout(ms)` (use sparingly)                            |
| `JSESSIONID` correlation rule                 | **Delete** — the browser handles cookies natively                          |
| Stripes `_sourcePage` / `__fp` correlation    | **Delete** — the browser submits the live form                             |
| `__VIEWSTATE` correlation                     | **Delete** — same                                                          |
| `LoopContainerAction` (N iterations)          | `for (let i = 0; i < N; i++) { ... }`                                      |
| `IfContainerAction` (condition)               | `if (cond) { ... }`                                                        |

**Most correlation rules become noise** in the Playwright translation
— the real browser submits the live form, sends the real cookies, and
echoes the real hidden inputs. Strip them. Keep only correlations that
extract a value the *user* visibly types (rare).

Minimal Playwright project layout — **keep it config-less**:

```
playwright-probe/
├── package.json
└── tests/
    └── user-journey.spec.ts
```

Why no `playwright.config.ts`? OctoPerf's importer treats every `.ts` /
`.js` file as a `PlaywrightSpecAction`, **including the config file**.
The engine then invokes the config as a test sampler at run time —
which fails (no `test()` defined) and inflates the failure count.

Disabling the config-as-spec (via `patch_virtual_user`,
`/children/<i>/enabled = false`) is a workaround, but it has a
second-order consequence: the config file is no longer written to
disk at run time → `use.baseURL` is lost → `page.goto('/')` becomes
`Cannot navigate to invalid URL`. The cleanest fix is to **skip the
config entirely** and put what you need in the spec:

- Use **absolute URLs** everywhere: `page.goto('https://target/path')`, never `page.goto('/path')`.
- Set headless / timeouts via `test.use({ ... })` at the top of the spec, not via `playwright.config.ts`.

Example spec (translated from a petstore-like JMeter VU):

```ts
import { test, expect } from '@playwright/test';

test('petstore browse + login probe', async ({ page }) => {
  const username = process.env.PETSTORE_USER ?? 'j2ee';
  const password = process.env.PETSTORE_PASSWORD ?? 'j2ee'