Add route interception and context-level request handling (#6)

Author: smnandre

README.md

@@ -10,35 +10,44 @@
 
 # Playwright for PHP
 
-Modern, PHP-native browser automation on top of Microsoft Playwright.
+Modern, PHP‑native browser automation powered by Microsoft Playwright.
 
-## Highlights
+## About
 
-- Powerful: Drive Chromium, Firefox, and WebKit with one API
-- Reliable: Auto-waits and locator model reduce flakiness
-- Expressive: Jest-style `expect()` assertions for pages and locators
-- Test-ready: PHPUnit integration and convenient test helpers
+Playwright for PHP lets you launch real browsers (Chromium, Firefox, WebKit), drive pages and locators, and write reliable end‑to‑end tests — all from PHP.
 
-## Requirements
+- Familiar model: browser → context → page → locator
+- Auto‑waiting interactions reduce flakiness
+- PHPUnit integration with a base test case and fluent `expect()` assertions
+- Cross‑browser: Chromium, Firefox, and WebKit supported
 
+Requirements:
 - PHP 8.3+
-- Node.js 20+ (used by the Playwright server and browser binaries)
+- Node.js 20+ (used by the bundled Playwright server and browsers)
 
 ## Install
 
+Add the library to your project:
+
 ```
 composer require playwright-php/playwright
 ```
 
-Optionnally, install the Playwright browsers:
+Install the Playwright browsers (Chromium, Firefox, WebKit):
 
 ```
-bin/playwright-install
+composer run install-browsers
+# or, if your environment needs extra OS deps
+composer run install-browsers-with-deps
 ```
 
-This installs the Node server dependencies under `bin/` and fetches Playwright browsers.
+The PHP library installs and manages a lightweight Node server under the hood; no manual server process is required.
+
+## Usage
+
+### Quick start
 
-## Quick Start
+Open a page and print its title:
 
 ```php
 <?php
@@ -47,68 +56,136 @@ require __DIR__.'/vendor/autoload.php';
 
 use PlaywrightPHP\Playwright;
 
-// Launch Chromium and get a context
 $context = Playwright::chromium(['headless' => true]);
-
-// Create a new page and navigate to a website
 $page = $context->newPage();
 $page->goto('https://example.com');
 
-// Print the page title
-echo $page->title().PHP_EOL; // "Example Domain"
+echo $page->title().PHP_EOL; // Example Domain
 
 $context->close();
 ```
 
-Tip: Debug with Inspector by running headed and pausing:
-- Env: `PWDEBUG=1 php your_script.php`
-- Builder: `$playwright->chromium()->withHeadless(false)->withInspector()->launch();` then `$page->pause();`
+### Browser
 
-Minimal `expect()` example:
+- Choose a browser: `Playwright::chromium()`, `Playwright::firefox()`, or `Playwright::webkit()`.
+- `Playwright::safari()` is an alias of `webkit()`.
+- Common launch options: `headless` (bool), `slowMo` (ms), `args` (array of CLI args), and an optional `context` array.
 
 ```php
-<?php
-require __DIR__.'/vendor/autoload.php';
+$context = Playwright::webkit([
+    'headless' => false,
+    'slowMo' => 200,
+    'args' => ['--no-sandbox'],
+]);
+```
 
-use PlaywrightPHP\Playwright;
-use function PlaywrightPHP\Testing\expect;
+### Page
 
-$context = Playwright::chromium();
+Create pages, navigate, evaluate scripts, and take screenshots:
+
+```php
 $page = $context->newPage();
 $page->goto('https://example.com');
 
-expect($page->locator('h1'))->toHaveText('Example Domain');
-expect($page->locator('h1 ~ p'))->toHaveCount(2);
+$html = $page->content();
+$title = $page->title();
+$path = $page->screenshot(__DIR__.'/screenshot.png');
 
-$context->close();
+$answer = $page->evaluate('() => 6 * 7'); // 42
 ```
 
-You can also run the ready-made example:
-- php docs/examples/example_expect.php
+### Locator
+
+Work with auto‑waiting locators for reliable interactions and assertions:
+
+```php
+use function PlaywrightPHP\Testing\expect;
+
+$h1 = $page->locator('h1');
+expect($h1)->toHaveText('Example Domain');
+
+$search = $page->locator('#q');
+$search->fill('playwright php');
+$page->locator('form')->submit();
+
+// Compose and filter
+$items = $page->locator('.result-item');
+expect($items)->toHaveCount(10);
+```
+
+### Server
+
+- A lightweight Node.js Playwright server is installed under `bin/` and started automatically by the PHP library.
+- Install browsers with: `composer run install-browsers` (or `install-browsers-with-deps`).
+- Requires Node.js 20+ in your environment (local and CI).
 
-## Scripts
+### Inspector (debugging)
 
-- composer test — runs the full test suite
-- composer analyse — static analysis (PHPStan)
-- composer cs-check — code style check
-- composer cs-fix — code style fix
-- composer run install-browsers — installs server deps and browsers (in `bin/`)
+- Run headed by setting `headless => false`.
+- Export `PWDEBUG=1` to open the Inspector: `PWDEBUG=1 php your_script.php`.
+- You can also call `$page->pause()` to break into the Inspector during a run.
+
+More examples: see `docs/examples/` (e.g., `php docs/examples/expect.php`).
+
+### Route interception
+
+Intercept and control network requests at page or context scope.
+
+- Page-level block (e.g., images):
+
+```php
+$page->route('**/*.png', function ($route) {
+    $route->abort(); // block images
+});
+```
+
+- Context-level stub API and pass-through others:
+
+```php
+$context->route('**/api/todos', function ($route) {
+    $route->fulfill([
+        'status' => 200,
+        'contentType' => 'application/json',
+        'body' => json_encode(['items' => []]),
+    ]);
+});
+
+$context->route('*', fn ($route) => $route->continue());
+```
+
+See runnable examples:
+- `php docs/examples/route_block_images.php`
+- `php docs/examples/route_stub_api.php`
+
+## Testing
+
+Integrate with PHPUnit using the provided base class:
+
+```php
+<?php
+
+use PlaywrightPHP\Testing\PlaywrightTestCase;
+use function PlaywrightPHP\Testing\expect;
+
+final class MyE2ETest extends PlaywrightTestCase
+{
+    public function test_homepage(): void
+    {
+        $this->page->goto('https://example.com');
+        expect($this->page->locator('h1'))->toHaveText('Example Domain');
+    }
+}
+```
 
-## Notes on the Server
+Tips:
+- On failure, screenshots are saved under `test-failures/`.
+- Enable tracing with `PW_TRACE=1` to capture a `trace.zip` for Playwright Trace Viewer.
+- Guides: `docs/guide/getting-started.md`, `docs/guide/testing-with-phpunit.md`, `docs/guide/assertions-reference.md`.
 
-- The Node-based Playwright server and its dependencies live under `bin/`.
-- Composer’s `install-browsers` script installs dependencies in `bin/` and runs `npx playwright install` there.
-- The PHP transport auto-starts the Node server as needed; no manual server process is required.
+## Contributing
 
-## Debugging with Playwright Inspector
+Contributions are welcome. Please use Conventional Commits, include tests for behavior changes, and ensure docs/examples are updated when relevant. See `docs/contributing/testing.md` for local workflow.
 
-- Enable Inspector via builder: call `withInspector()` and run headed.
-  - Example: `$browser = $playwright->chromium()->withHeadless(false)->withInspector()->launch();`
-- Pause at a point to open Inspector: `$page->pause();`
-- Alternatively, export `PWDEBUG` when running your script to enable Inspector globally:
-  - macOS/Linux: `PWDEBUG=1 php your_script.php`
-  - Windows (PowerShell): `$env:PWDEBUG='1'; php your_script.php`
+## Licence
 
-Notes:
-- Inspector opens from the Node server; `PWDEBUG` is forwarded automatically.
-- A headed browser (`headless: false`) makes it easier to see UI interactions while debugging.
+MIT — see `LICENSE` for details.

bin/playwright-server.js

@@ -289,6 +289,39 @@ class PlaywrightServer {
       case 'stopTracing':
         await context.tracing.stop({ path: command.path });
         return {success: true};
+      case 'route':
+        await context.route(command.url, async (route) => {
+          const routeId = `route_${++this.routeCounter}`;
+          this.routes.set(routeId, route);
+
+          const req = route.request();
+          let postData = null;
+          try {
+            postData = req.postData();
+          } catch (e) {
+            postData = null;
+          }
+          debugLogger.info('CTX ROUTE', { url: req.url(), method: req.method() });
+          const event = {
+            objectId: command.contextId,
+            event: 'route',
+            params: {
+              routeId,
+              request: {
+                url: req.url(),
+                method: req.method(),
+                headers: req.headers(),
+                postData: postData ?? null,
+                resourceType: req.resourceType ? req.resourceType() : 'document'
+              }
+            }
+          };
+          sendFramedResponse(event);
+        });
+        return {success: true};
+      case 'unroute':
+        await context.unroute(command.url);
+        return {success: true};
       case 'newPage':
         const page = await context.newPage(command.options);
         const pageId = `page_${++this.pageCounter}`;
@@ -327,8 +360,36 @@ class PlaywrightServer {
         const gotoResponse = await page.goto(command.url, command.options);
         return {response: this.serializeResponse(gotoResponse)};
       case 'evaluate':
-        const result = await page.evaluate(command.expression, command.arg);
-        return {result};
+        try {
+          // Attempt function-like evaluation first to support strings like '() => 42' or 'async () => {...}'
+          const attempt = await page.evaluate(async ({expression, arg}) => {
+            try {
+              const func = eval(`(${expression})`);
+              if (typeof func === 'function') {
+                const value = await func(arg);
+                return { ok: true, value };
+              }
+              return { ok: false, reason: 'not-a-function' };
+            } catch (e) {
+              return { ok: false, reason: e.message };
+            }
+          }, {expression: command.expression, arg: command.arg});
+
+          if (attempt && attempt.ok === true) {
+            const value = attempt.value === undefined ? null : attempt.value;
+            debugLogger.info('PAGE EVALUATE(FUNC) OK', { type: typeof value });
+            return {result: value};
+          }
+
+          // Fallback: treat expression as direct JS expression (e.g., 'window.foo')
+          const result = await page.evaluate(command.expression, command.arg);
+          const value = result === undefined ? null : result;
+          debugLogger.info('PAGE EVALUATE(EXPR) OK', { type: typeof value });
+          return {result: value};
+        } catch (error) {
+          debugLogger.error('PAGE EVALUATE ERROR', { message: error.message });
+          throw error;
+        }
       case 'waitForResponse':
         const jsAction = command.jsAction;
         const [response] = await Promise.all([
@@ -390,6 +451,7 @@ class PlaywrightServer {
           } catch (e) {
             postData = null;
           }
+          debugLogger.info('PAGE ROUTE', { url: req.url(), method: req.method() });
           const event = {
             objectId: command.pageId,
             event: 'route',
@@ -539,11 +601,17 @@ class PlaywrightServer {
 
     switch (method) {
       case 'fulfill':
+        debugLogger.info('ROUTE FULFILL', { routeId: command.routeId });
         await route.fulfill(command.options);
         break;
       case 'abort':
+        debugLogger.info('ROUTE ABORT', { routeId: command.routeId, errorCode: command.errorCode });
         await route.abort(command.errorCode);
         break;
+      case 'continue':
+        debugLogger.info('ROUTE CONTINUE', { routeId: command.routeId });
+        await route.continue(command.options || undefined);
+        break;
       default:
         throw new Error(`Unknown route action: ${method}`);
     }

docs/examples/route_block_images.php

@@ -0,0 +1,28 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * This file is part of the playwright-php/playwright package.
+ * For the full copyright and license information, please view
+ * the LICENSE file that was distributed with this source code.
+ */
+
+require_once __DIR__.'/../../vendor/autoload.php';
+
+use PlaywrightPHP\Playwright;
+
+$context = Playwright::chromium([
+    'headless' => true,
+]);
+$page = $context->newPage();
+
+// Block PNG images on this page
+$page->route('**/*.png', function ($route): void {
+    $route->abort();
+});
+
+$page->goto('https://example.com');
+echo 'Loaded example.com with images blocked'.PHP_EOL;
+
+$context->close();