+ Order ready
+ Your notebook and pen are packed.
+
+
+
+"""
+page_url = "data:text/html;charset=utf-8," + quote(html)
+output_path = Path("screenshot_element.png")
+
+
+with sync_playwright() as playwright:
+ browser = playwright.chromium.launch(headless=True)
+ try:
+ page = browser.new_page()
+ page.goto(page_url)
+
+ # Locator screenshots capture only the matching element, not the full page.
+ page.locator(".receipt").screenshot(path=str(output_path))
+ print(f"saved: {output_path}")
+ finally:
+ browser.close()
diff --git a/node/package.json b/node/package.json
index 4ddc732..0fcfcfb 100644
--- a/node/package.json
+++ b/node/package.json
@@ -41,7 +41,7 @@
"scripts": {
"build": "napi build --release -p rustwright-node --dts native.d.ts && node ./scripts/generate-types.mjs",
"smoke": "node ./smoke.mjs",
- "test": "node --test test/"
+ "test": "node --test"
},
"devDependencies": {
"@napi-rs/cli": "^2.18.4"
diff --git a/node/test/quickstart.test.mjs b/node/test/quickstart.test.mjs
new file mode 100644
index 0000000..1c5c54b
--- /dev/null
+++ b/node/test/quickstart.test.mjs
@@ -0,0 +1,132 @@
+import assert from 'node:assert/strict';
+import { spawnSync } from 'node:child_process';
+import {
+ existsSync,
+ mkdirSync,
+ mkdtempSync,
+ readFileSync,
+ rmSync,
+ writeFileSync,
+} from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import test from 'node:test';
+import { fileURLToPath } from 'node:url';
+
+const testDirectory = dirname(fileURLToPath(import.meta.url));
+const repoRoot = resolve(testDirectory, '../..');
+const examplePath = resolve(repoRoot, 'examples/quickstart.js');
+
+test('Node quickstart runs from the repository root', { timeout: 45_000 }, async (t) => {
+ assert.ok(
+ existsSync(examplePath),
+ 'examples/quickstart.js is missing; add the runnable Node.js quickstart example',
+ );
+
+ const quickstartSource = readFileSync(examplePath, 'utf8');
+ assert.match(
+ quickstartSource,
+ /^\/\/ const \{ chromium \} = require\('rustwright'\);$/m,
+ 'npm-user guidance must use CommonJS syntax because the example is CommonJS',
+ );
+
+ const probeRoot = mkdtempSync(join(tmpdir(), 'rustwright-quickstart-test-'));
+ try {
+ const commonjsProject = join(probeRoot, 'commonjs-project');
+ const commonjsPackage = join(commonjsProject, 'node_modules', 'rustwright');
+ mkdirSync(commonjsPackage, { recursive: true });
+ writeFileSync(join(commonjsProject, 'package.json'), '{"type":"commonjs"}\n');
+ writeFileSync(
+ join(commonjsPackage, 'package.json'),
+ '{"name":"rustwright","main":"index.cjs"}\n',
+ );
+ writeFileSync(join(commonjsPackage, 'index.cjs'), "exports.chromium = 'stub';\n");
+ const commonjsProbe = join(commonjsProject, 'quickstart.js');
+ writeFileSync(
+ commonjsProbe,
+ "const { chromium } = require('rustwright');\nif (chromium !== 'stub') process.exitCode = 1;\n",
+ );
+
+ const syntaxResult = spawnSync(process.execPath, ['--check', commonjsProbe], {
+ encoding: 'utf8',
+ });
+ assert.equal(syntaxResult.status, 0, syntaxResult.stderr);
+ const commonjsResult = spawnSync(process.execPath, [commonjsProbe], { encoding: 'utf8' });
+ assert.equal(commonjsResult.status, 0, commonjsResult.stderr);
+
+ const brokenProject = join(probeRoot, 'broken-package-project');
+ const brokenPackage = join(brokenProject, 'node_modules', 'rustwright');
+ mkdirSync(brokenPackage, { recursive: true });
+ writeFileSync(
+ join(brokenPackage, 'package.json'),
+ '{"name":"rustwright","main":"index.cjs"}\n',
+ );
+ writeFileSync(join(brokenPackage, 'index.cjs'), "require('./missing-internal.cjs');\n");
+ writeFileSync(join(brokenProject, 'quickstart.js'), quickstartSource);
+
+ const localFallback = join(probeRoot, 'node');
+ mkdirSync(localFallback);
+ writeFileSync(
+ join(localFallback, 'index.cjs'),
+ `exports.chromium = {
+ async launch() {
+ return {
+ async newPage() {
+ return {
+ async goto() {},
+ async title() { return 'unexpected fallback'; },
+ async screenshot() {},
+ async close() {},
+ };
+ },
+ async close() {},
+ };
+ },
+};
+`,
+ );
+
+ const brokenResult = spawnSync(process.execPath, ['quickstart.js'], {
+ cwd: brokenProject,
+ encoding: 'utf8',
+ });
+ assert.notEqual(brokenResult.status, 0, 'a broken installed package must not use the fallback');
+ assert.match(brokenResult.stderr, /Cannot find module '\.\/missing-internal\.cjs'/);
+ assert.match(brokenResult.stderr, /node_modules[\\/]rustwright[\\/]index\.cjs/);
+ } finally {
+ rmSync(probeRoot, { recursive: true, force: true });
+ }
+
+ let chromium;
+ try {
+ ({ chromium } = await import('../index.mjs'));
+ } catch (error) {
+ if (error instanceof Error && error.message.includes('native addon is not built')) {
+ t.skip('Rustwright native addon is not built');
+ return;
+ }
+ throw error;
+ }
+
+ if (!await chromium.executablePath()) {
+ t.skip('Chromium/Chrome executable not found');
+ return;
+ }
+
+ const result = spawnSync(process.execPath, ['examples/quickstart.js'], {
+ cwd: repoRoot,
+ encoding: 'utf8',
+ env: process.env,
+ timeout: 30_000,
+ });
+
+ assert.equal(result.error, undefined, `quickstart process error: ${result.error?.message}`);
+ assert.equal(
+ result.status,
+ 0,
+ `quickstart exited with status ${result.status}\nstdout:\n${result.stdout}\nstderr:\n${result.stderr}`,
+ );
+
+ // Output contract: the quickstart prints the title from its inline page.
+ assert.match(result.stdout, /^title: Rustwright works$/m);
+});
diff --git a/tests/test_changelog.py b/tests/test_changelog.py
new file mode 100644
index 0000000..27f3668
--- /dev/null
+++ b/tests/test_changelog.py
@@ -0,0 +1,179 @@
+from __future__ import annotations
+
+import re
+from datetime import date
+from pathlib import Path
+
+import pytest
+
+
+ROOT = Path(__file__).resolve().parents[1]
+CHANGELOG = ROOT / "CHANGELOG.md"
+REQUIRED_VERSIONS = (
+ "0.1.1",
+ "0.1.0",
+ "0.1.0-alpha.4",
+ "0.1.0-alpha.3",
+)
+PRERELEASE_IDENTIFIER = r"(?:0|[1-9]\d*|[0-9A-Za-z-]*[A-Za-z-][0-9A-Za-z-]*)"
+BUILD_IDENTIFIER = r"[0-9A-Za-z-]+"
+VERSION_RE = re.compile(
+ rf"(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)"
+ rf"(?:-({PRERELEASE_IDENTIFIER}(?:\.{PRERELEASE_IDENTIFIER})*))?"
+ rf"(?:\+({BUILD_IDENTIFIER}(?:\.{BUILD_IDENTIFIER})*))?"
+)
+SECTION_RE = re.compile(
+ r"^## \[([^\]]+)\](?: - ([^\r\n]+))?\s*$",
+ re.MULTILINE,
+)
+CATEGORY_RE = re.compile(
+ r"^### (?:Added|Changed|Fixed|Deprecated|Removed|Security)\s*$",
+ re.MULTILINE,
+)
+NEXT_H2_RE = re.compile(r"^## ", re.MULTILINE)
+NEXT_H3_RE = re.compile(r"^### ", re.MULTILINE)
+BULLET_RE = re.compile(r"^- .+", re.MULTILINE)
+
+
+def _version_key(
+ version: str,
+) -> tuple[int, int, int, tuple[int, tuple[tuple[int, int | str], ...]]]:
+ match = VERSION_RE.fullmatch(version)
+ assert match is not None, f"unsupported changelog version: {version}"
+ major, minor, patch, prerelease, _build = match.groups()
+ prerelease_key = (
+ (1, ())
+ if prerelease is None
+ else (
+ 0,
+ tuple(
+ (0, int(identifier)) if identifier.isdigit() else (1, identifier)
+ for identifier in prerelease.split(".")
+ ),
+ )
+ )
+ return int(major), int(minor), int(patch), prerelease_key
+
+
+def _version_sections(text: str) -> list[re.Match[str]]:
+ sections = [
+ section
+ for section in SECTION_RE.finditer(text)
+ if section.group(1) != "Unreleased"
+ ]
+ unsupported = [
+ section.group(1)
+ for section in sections
+ if VERSION_RE.fullmatch(section.group(1)) is None
+ ]
+ assert not unsupported, (
+ "unsupported changelog version heading: " + ", ".join(unsupported)
+ )
+ return sections
+
+
+def _assert_version_sections_strictly_descending(text: str) -> None:
+ versions = [section.group(1) for section in _version_sections(text)]
+ duplicates = sorted({version for version in versions if versions.count(version) > 1})
+ assert not duplicates, "version sections must be unique: " + ", ".join(duplicates)
+
+ for newer, older in zip(versions, versions[1:]):
+ assert _version_key(newer) > _version_key(older), (
+ "version sections must appear newest first: "
+ f"{newer} must be newer than {older}"
+ )
+
+
+def _has_category_with_bullet(section_body: str) -> bool:
+ for category in CATEGORY_RE.finditer(section_body):
+ next_category = NEXT_H3_RE.search(section_body, category.end())
+ category_end = next_category.start() if next_category else len(section_body)
+ if BULLET_RE.search(section_body, category.end(), category_end):
+ return True
+ return False
+
+
+def test_changelog_has_required_structure() -> None:
+ assert CHANGELOG.is_file(), "CHANGELOG.md must exist at the repository root"
+ text = CHANGELOG.read_text(encoding="utf-8")
+
+ headings = re.findall(r"^#{1,6} .+$", text, re.MULTILINE)
+ assert headings, "CHANGELOG.md must contain Markdown headings"
+ assert headings[0] == "# Changelog", "the first heading must be '# Changelog'"
+
+ sections = list(SECTION_RE.finditer(text))
+ unreleased = [section for section in sections if section.group(1) == "Unreleased"]
+ assert unreleased, "CHANGELOG.md must contain an exact '## [Unreleased]' section"
+ assert unreleased[0].group(2) is None, "the Unreleased section must not have a date"
+
+ version_sections = _version_sections(text)
+ assert version_sections, "CHANGELOG.md must contain version sections"
+ assert unreleased[0].start() < version_sections[0].start(), (
+ "the Unreleased section must appear before every version section"
+ )
+
+ version_names = [section.group(1) for section in version_sections]
+ missing = [version for version in REQUIRED_VERSIONS if version not in version_names]
+ assert not missing, f"CHANGELOG.md is missing published versions: {', '.join(missing)}"
+ _assert_version_sections_strictly_descending(text)
+
+ for section in version_sections:
+ version, released_on = section.groups()
+ assert released_on is not None, f"version {version} must have a YYYY-MM-DD date"
+ try:
+ parsed_date = date.fromisoformat(released_on)
+ except ValueError:
+ parsed_date = None
+ assert parsed_date is not None and parsed_date.isoformat() == released_on, (
+ f"version {version} must have a valid YYYY-MM-DD date"
+ )
+
+ next_section = NEXT_H2_RE.search(text, section.end())
+ section_end = next_section.start() if next_section else len(text)
+ section_body = text[section.end() : section_end]
+ assert _has_category_with_bullet(section_body), (
+ f"version {version} must contain a recognized category with a '- ' bullet"
+ )
+
+
+def test_version_order_rejects_out_of_order_fixture() -> None:
+ fixture = """\
+## [0.1.1] - 2026-07-15
+## [9.0.0] - 2026-07-16
+## [0.1.0] - 2026-07-14
+"""
+
+ with pytest.raises(AssertionError, match="newest first"):
+ _assert_version_sections_strictly_descending(fixture)
+
+
+def test_version_order_rejects_duplicate_fixture() -> None:
+ fixture = """\
+## [1.0.0] - 2026-07-16
+## [1.0.0-alpha.1] - 2026-07-15
+## [1.0.0-alpha.1] - 2026-07-14
+"""
+
+ with pytest.raises(AssertionError, match="must be unique"):
+ _assert_version_sections_strictly_descending(fixture)
+
+
+def test_version_order_rejects_misordered_beta_fixture() -> None:
+ fixture = """\
+## [1.0.0-beta.2] - 2026-07-16
+## [1.0.0-beta.10] - 2026-07-15
+## [1.0.0-alpha.1] - 2026-07-14
+"""
+
+ with pytest.raises(AssertionError, match="newest first"):
+ _assert_version_sections_strictly_descending(fixture)
+
+
+def test_version_order_rejects_unrecognized_heading_fixture() -> None:
+ fixture = """\
+## [1.0.0] - 2026-07-16
+## [release-next] - 2026-07-15
+"""
+
+ with pytest.raises(AssertionError, match="unsupported changelog version heading"):
+ _assert_version_sections_strictly_descending(fixture)
diff --git a/tests/test_examples.py b/tests/test_examples.py
new file mode 100644
index 0000000..8203c11
--- /dev/null
+++ b/tests/test_examples.py
@@ -0,0 +1,132 @@
+from __future__ import annotations
+
+import ast
+import struct
+import subprocess
+import sys
+from functools import lru_cache
+from pathlib import Path
+
+import pytest
+
+
+ROOT = Path(__file__).resolve().parents[1]
+EXAMPLES = ROOT / "examples"
+EXAMPLE_TIMEOUT_SECONDS = 60
+SCREENSHOT_OUTPUT = ROOT / "screenshot_element.png"
+
+
+def _required_example(filename: str) -> Path:
+ script = EXAMPLES / filename
+ assert script.is_file(), f"Missing required example script: examples/{filename}"
+ return script
+
+
+@lru_cache(maxsize=1)
+def _chromium_probe() -> subprocess.CompletedProcess[str]:
+ return subprocess.run(
+ [
+ sys.executable,
+ "-c",
+ (
+ "from rustwright.sync_api import sync_playwright; "
+ "playwright = sync_playwright().start(); "
+ "print('available' if playwright.chromium.executable_path else 'missing'); "
+ "playwright.stop()"
+ ),
+ ],
+ cwd=ROOT,
+ text=True,
+ capture_output=True,
+ timeout=20,
+ )
+
+
+def _require_chromium() -> None:
+ probe = _chromium_probe()
+ assert probe.returncode == 0, (
+ "Could not inspect Rustwright's Chromium installation.\n"
+ f"stdout:\n{probe.stdout}\n"
+ f"stderr:\n{probe.stderr}"
+ )
+ if probe.stdout.strip() == "missing":
+ pytest.skip("Chromium/Chrome executable not found")
+ assert probe.stdout.strip() == "available", probe.stdout
+
+
+def _run_example(filename: str) -> subprocess.CompletedProcess[str]:
+ script = _required_example(filename)
+ _require_chromium()
+ result = subprocess.run(
+ [sys.executable, str(script)],
+ cwd=ROOT,
+ text=True,
+ capture_output=True,
+ timeout=EXAMPLE_TIMEOUT_SECONDS,
+ )
+ assert result.returncode == 0, (
+ f"examples/{filename} exited with status {result.returncode}.\n"
+ f"stdout:\n{result.stdout}\n"
+ f"stderr:\n{result.stderr}"
+ )
+ return result
+
+
+def _marker_value(stdout: str, marker: str) -> str:
+ matching_lines = [line for line in stdout.splitlines() if line.startswith(marker)]
+ assert matching_lines, f"Expected stdout to contain a line starting with {marker!r}.\nstdout:\n{stdout}"
+ assert len(matching_lines) == 1, f"Expected exactly one {marker!r} line, got {matching_lines!r}"
+ return matching_lines[0][len(marker) :].strip()
+
+
+def test_fill_form_example() -> None:
+ """Contract: submit two fields and print `submitted: Ada Lovelace (ada@example.test)`."""
+ result = _run_example("fill_form.py")
+
+ submitted = _marker_value(result.stdout, "submitted: ")
+ assert submitted == "Ada Lovelace (ada@example.test)"
+
+
+def test_scrape_table_example() -> None:
+ """Contract: print `rows: ` followed by this fixture table as a list of dictionaries."""
+ result = _run_example("scrape_table.py")
+
+ rendered_rows = _marker_value(result.stdout, "rows: ")
+ try:
+ rows = ast.literal_eval(rendered_rows)
+ except (SyntaxError, ValueError) as exc:
+ raise AssertionError(f"The rows marker must contain a Python literal, got {rendered_rows!r}") from exc
+ assert rows == [
+ {"Product": "Notebook", "Price": "$4.50", "Stock": "12"},
+ {"Product": "Pen", "Price": "$1.25", "Stock": "40"},
+ ]
+
+
+def test_screenshot_element_example() -> None:
+ """Contract: save one element to `screenshot_element.png` and print `saved: