feat(plugins): add expose plugin for direct helper-internals injection

[DavertMik]

Summary

Adds a new expose plugin that injects helper internals (Playwright/Puppeteer page, browser, browserContext; WebDriver browser/wdio client; or any helper property) as destructurable scenario arguments.

plugins: {
  expose: {
    enabled: true,
    inject: {
      page: 'Playwright.page',
      browser: 'Playwright.browser',
      wdio: 'WebDriver.browser',
    }
  }
}

// in a test
Scenario('intercept network', async ({ I, page }) => {
  page.on('request', r => console.log(r.url()))
  await page.evaluate(() => 1 + 1)
  I.amOnPage('/')
})

Shorthand inject: { page: 'page' } resolves to the first configured browser helper that exposes the property.

Design highlights

• Live proxy, not a snapshot. Each property access re-reads Container.helpers(name)?.[property], so mid-test reassignments from switchToNextTab, openNewTab, switchToPreviousTab (Playwright _setPage calls at lines 1864/1890/1948; Puppeteer at 1112/1135/1180) are reflected automatically.
• Bypasses MetaStep wrapping. Registers a Proxy(function(){}, ...) so typeof === 'function' triggers the short-circuit in Container.support() (lib/container.js:171-173) — the proxy is returned as-is and method calls run as native Playwright/Puppeteer SDK calls (no extra step lines, no proxy semantics altering behavior).
• Dry-run safe. When helper.page is null or undefined (dry-run, before _before, after _stopBrowser), the proxy returns undefined for any property access instead of throwing.
• Validation at boot. Throws clear errors for missing helpers, reserved injection names (I, test, suite), unknown shorthand properties, and malformed values.

Files

• lib/plugin/expose.js — plugin implementation (~150 lines)
• test/unit/plugin/expose_test.js — 13 unit tests covering live reassignment, null tolerance, this-binding, raw return values, shorthand resolution, and validation paths
• docs/advanced.md — new "Direct Helper Access" section

Test plan

• npx mocha test/unit/plugin/expose_test.js — 13/13 pass
• npx mocha test/unit/plugin/ — full plugin suite green (no regression)
• ./bin/codecept.js dry-run --config test/acceptance/codecept.Playwright.js — clean, all 77 tests load
• Acceptance scenario destructuring ({ I, page }) against real Playwright (manual)
• Tab-switch test: open popup, then await page.url() must reflect new tab (manual)

🤖 Generated with Claude Code