js_tgbrowser/README.md

Playwright helpers for connecting to TestGrid remote browsers via Selenium + CDP.

# TestGrid Playwright Helpers

Utilities to run Playwright tests against TestGrid-managed browsers. The package provides:

- `setupTestgrid` – bootstraps Playwright to use a remote Selenium session via CDP.
- Custom Playwright fixture (`testgrid.fixture`) that connects tests to the remote browser.
- `inspect-session` script to debug Selenium sessions.
- Post-install hook that drops `TESTGRID_BROWSER_SETUP.md` into the consumer project for quick reference.

## Install

```bash
npm install js_tgbrowser
```

## Quick Start

| Runtime | Import snippet |
| --- | --- |
| JavaScript | `const { setupTestgrid } = require('js_tgbrowser');` |
| TypeScript | `import { setupTestgrid } from 'js_tgbrowser';` |

**JavaScript example**

```javascript
// playwright.config.js
const { defineConfig } = require('@playwright/test');
const { setupTestgrid } = require('js_tgbrowser');

const testgridConfig = setupTestgrid({
  remoteUrl: process.env.SELENIUM_REMOTE_URL,
  capabilities: JSON.parse(process.env.SELENIUM_REMOTE_CAPABILITIES || '{}'),
  cdpProxyPath: process.env.TESTGRID_CDP_PROXY_PATH,
  debugScopes: process.env.DEBUG || 'pw:api'
});

module.exports = defineConfig({
  testDir: './tests',
  metadata: {
    testgrid: testgridConfig
  }
});
```

**TypeScript example**

```typescript
// playwright.config.ts
import { defineConfig } from '@playwright/test';
import { setupTestgrid } from 'js_tgbrowser';

const testgridConfig = setupTestgrid({
  remoteUrl: process.env.SELENIUM_REMOTE_URL!,
  capabilities: JSON.parse(process.env.SELENIUM_REMOTE_CAPABILITIES || '{}'),
  cdpProxyPath: process.env.TESTGRID_CDP_PROXY_PATH,
  debugScopes: process.env.DEBUG || 'pw:api'
});

export default defineConfig({
  testDir: './tests',
  metadata: {
    testgrid: testgridConfig
  }
});
```

`hostHeader` is optional—if omitted the helper uses the hostname from `remoteUrl`. See `TESTGRID_BROWSER_SETUP.md` for the complete integration checklist.