{"pagination":{},"data":{"collaborations":[],"createdDate":"2026-09-30T12:50:29-05:00","isActive":true,"description":"# ⚡︎ BoxLang Playwright\n\n```\n|:------------------------------------------------------:|\n| ⚡︎ B o x L a n g ⚡︎\n| Dynamic : Modular : Productive\n|:------------------------------------------------------:|\n```\n\n<blockquote>\n\tCopyright Since 2023 by Ortus Solutions, Corp\n\t<br>\n\t<a href=\"https://www.boxlang.io\">www.boxlang.io</a> |\n\t<a href=\"https://www.ortussolutions.com\">www.ortussolutions.com</a>\n</blockquote>\n\nFluent browser automation and testing for BoxLang, powered by [Microsoft Playwright](https://playwright.dev). Drive Chromium, Firefox and WebKit, test web apps, mock the network, test APIs, and render HTML to PDF or images.\n\n## Install\n\nTwo distributions, same module (`playwright`), same API:\n\n| Module | Size | Node.js |\n|---|---|---|\n| `bx-playwright` | ~4 MB | Downloaded by `bxPlaywright install` for your OS |\n| `bx-playwright-full` | ~206 MB | Bundled for every platform (offline friendly) |\n\n```bash\ninstall-bx-module bx-playwright\nbxPlaywright install            # driver + Node.js + Chromium\nbxPlaywright install firefox webkit\nbxPlaywright doctor             # check everything\n```\n\nRequires BoxLang 1.17+ and Java 21+.\n\n## Quick Start\n\n```js\nplaywright().visit( \"https://boxlang.io\" )\n\t.assertTitleContains( \"BoxLang\" )\n\t.click( \"Docs\" )\n\t.screenshot( \"docs.png\" )\n\t.quit()\n```\n\n```js\n// Scoped work, cleaned up automatically\nplaywright( \"mobile\" ).browse( ( page ) => {\n\tpage.visit( \"http://localhost:8080/login\" )\n\t\t.fill( \"Email\", \"luis@ortus.com\" )     // by label, placeholder or name\n\t\t.fill( \"Password\", \"secret\" )\n\t\t.click( \"Sign in\" )                    // by button or link text\n\t\t.assertPathIs( \"/dashboard\" )\n\t\t.assertSee( \"Welcome\" )\n} )\n```\n\n```js\n// One-shot helpers\nplaywright().screenshot( \"https://boxlang.io\", \"home.png\", { fullPage : true } )\nplaywright().pdf( \"https://boxlang.io\", \"home.pdf\", { format : \"A4\" } )\nhtml = playwright().content( \"https://boxlang.io\" )     // rendered HTML\n```\n\n```html\n<bx:playwrightRender type=\"pdf\" path=\"invoice.pdf\" format=\"A4\" margin=\"1cm\">\n\t<h1>Invoice #invoice.id#</h1>\n</bx:playwrightRender>\n```\n\n## The API in One Screen\n\n| Area | API |\n|---|---|\n| Entry | `playwright( [profile], [options] )`, `.visit()`, `.browse()`, `.newContext()`, `.newPage()`, `.request()`, `.render()`, `.close()` |\n| Selectors | `@testId`, CSS / XPath (`#id`, `.class`, `h1`, `//div`), or visible text (labels for `fill`, buttons and links for `click`) |\n| Actions | `click`, `dblclick`, `fill`, `type`, `clear`, `press`, `check`, `uncheck`, `select`, `upload`, `hover`, `focus`, `drag`, `scrollTo` |\n| Finders | `locator`, `byRole`, `byText`, `byLabel`, `byPlaceholder`, `byTestId`, `byAltText`, `byTitle`, `frame`, `within` |\n| Locators | `first`, `last`, `nth` (1-based), `filter`, `visible`, `all`, `count`, `texts` |\n| Assertions | `assertSee`, `assertDontSee`, `assertTitle`, `assertPathIs`, `assertUrlIs`, `assertVisible`, `assertMissing`, `assertText`, `assertValue`, `assertChecked`, `assertCount`, ... |\n| Expect | `page.expect( \"h1\" ).toHaveText( \"Hi\" )`, `.not().toBeVisible()`, `toHaveURL`, `toHaveCount`, `toMatchAriaSnapshot`, ... |\n| Network | `intercept( \"**/api/users\" ).respondJson( data )`, `.respond()`, `.abort()`, `.resume()`, `.handle()` |\n| Events | `onConsole`, `onPageError`, `onDialog`, `onRequest`, `onResponse`, `waitForPopup`, `waitForDownload` |\n| Output | `screenshot`, `pdf`, `content`, `text`, `html`, `snapshot` (accessibility tree for AI agents) |\n\nAssertions retry until they pass (web-first). Failures throw `Playwright.AssertionFailed` with Playwright's message. Other errors: `Playwright.Timeout`, `Playwright.ActionFailed`, `Playwright.InvalidOption`, `Playwright.InvalidProfile`, `Playwright.NotInstalled`.\n\n## Profiles\n\n`playwright( \"mobile\" )`, `playwright( [ \"android\", \"dark\" ] )`. Built-in: `default`, `chromium`, `firefox`, `webkit`, `chrome`, `chrome-beta`, `edge`, `hd`, `laptop`, `macbook`, `desktop`, `4k`, `mobile`/`iphone`, `iphone-se`, `mobile-landscape`, `android`/`pixel`, `galaxy`, `tablet`/`ipad`, `android-tablet`, `dark`, `light`, `reduced-motion`, `high-contrast`, `headed`, `debug`, `record`, `ci`, `offline`, `print`, `screenshot`.\n\nAdd your own in the module settings, extending any profile:\n\n```json\n\"modules\": {\n\t\"playwright\": {\n\t\t\"settings\": {\n\t\t\t\"baseURL\": \"http://localhost:8080\",\n\t\t\t\"profiles\": { \"staging\": { \"extends\": \"desktop\", \"baseURL\": \"https://staging.example.com\" } }\n\t\t}\n\t}\n}\n```\n\nResolution order (last wins): module settings, profiles, `BX_PLAYWRIGHT_*` environment variables (`BROWSER`, `HEADLESS`, `BASEURL`; `PROFILE` picks the default profile), per-call options.\n\n## CLI\n\n`bxPlaywright <verb>` (or `boxlang module:playwright <verb>`): `install`, `install-node`, `install-deps`, `uninstall`, `doctor`, `version`, `devices`, `profiles`, `clean`, `codegen`, `open`, `screenshot`, `pdf`, `show-trace`, `mcp`, `run`, `completions`, `help`. Add `--json` for machine readable output. Bash completions are installed with the module.\n\n## Development\n\n```bash\n./gradlew downloadBoxLang\n./gradlew shadowJar test                          # unit and integration tests\nPLAYWRIGHT_E2E=true ./gradlew shadowJar test      # plus real browser tests (downloads Node.js and Chromium once)\n./gradlew shadowJar -Pflavor=full                 # build bx-playwright-full\n./gradlew spotlessApply                           # Ortus formatting\n```\n\nSee [AGENTS.md](AGENTS.md) for the architecture and conventions, and [PLAN.md](PLAN.md) for the roadmap.\n\n## Ortus Sponsors\n\nBoxLang is a professional open-source project and it is completely funded by the [community](https://patreon.com/ortussolutions) and [Ortus Solutions, Corp](https://www.ortussolutions.com). Ortus Patreons get many benefits like a cfcasts account, a FORGEBOX Pro account and so much more. If you are interested in becoming a sponsor, please visit our patronage page: [https://patreon.com/ortussolutions](https://patreon.com/ortussolutions)\n\n### THE DAILY BREAD\n\n> \"I am the way, and the truth, and the life; no one comes to the Father, but by me (JESUS)\" Jn 14:1-12\n","title":"BoxLang Playwright","entryType":{"typeSlug":"boxlang-modules","typeName":"BoxLang Modules"},"homeURL":"https://github.com/ortus-boxlang/bx-playwright","downloads":0,"installInstructions":"","latestVersionUpdatedDate":"2026-10-23T16:01:28-05:00","typeSlug":"boxlang-modules","latestVersion":{"binaryHash":"","sortOrder":1,"downloadURL":"https://downloads.ortussolutions.com/ortussolutions/boxlang-modules/bx-playwright/1.0.0-snapshot/bx-playwright-1.0.0-snapshot.zip","version":"1.0.0-snapshot","installs":1453},"slug":"bx-playwright","avgRating":"0.0000","documentationURL":"https://bxplaywright.boxlang.io","summary":"Fluent browser automation and testing for BoxLang, powered by Microsoft Playwright","isPrivate":false,"changelogFormat":"md","installInstructionsFormat":"text","changelog":"# Changelog\n\nAll notable changes to this project will be documented in this file.\n\nThe format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),\nand this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).\n\n----\n\n## [Unreleased]\n\n### Added\n\n* `playwright()` BIF: fluent browser automation with smart selectors, chainable actions, web-first assertions (inline and `expect()` style), network mocking, events, popups, downloads, screenshots, PDF, rendered content and accessibility snapshots\n* `browse()` with automatic cleanup and multi-user pages, one-shot `screenshot()`, `pdf()`, `content()` and `render()`\n* `request()` for API testing\n* `bx:playwrightRender` component: render HTML to PDF, PNG, JPEG or WebP with Chromium\n* Built-in profiles (browsers, screens, devices, appearance, modes), user profiles with `extends`, `BX_PLAYWRIGHT_*` environment overrides\n* Artifact policies for screenshots, traces and videos (`off`, `on`, `only-on-failure`, `retain-on-failure`)\n* `bxPlaywright` CLI with bash completions and `--json` output: install, install-node, install-deps, uninstall, doctor, version, devices, profiles, clean, codegen, open, screenshot, pdf, show-trace, mcp, run, completions, help\n* Two distributions: `bx-playwright` (downloads Node.js) and `bx-playwright-full` (bundles Node.js)\n* Interception points: onPlaywrightCreate, onBrowserLaunch, onContextCreate, onPageCreate, onPageClose, onPlaywrightAssertionFailure, onPlaywrightArtifact\n* Visual regression: `assertScreenshotMatches()` with baselines, pixel diff and diff images (`snapshots` setting, `BX_PLAYWRIGHT_UPDATE_SNAPSHOTS`)\n* Quality checks: `assertNoConsoleErrors()`, `assertNoSmoke()`, axe-core `accessibility()` and `assertNoAccessibilityIssues()`\n* Page objects, page components and `macro()` extensions\n* Soft assertions with `soft()`\n* Emulation with `emulate()`, `device()`, `clock()` and `freezeTime()`\n* `session( name, setup )` caches logged in storage state\n* `codegen` translates recorded actions into the bx-playwright DSL\n* AI support: `snapshot()` with element refs, `help()` introspection, `aiTools()` for bx-ai\n* Runnable `examples/` executed in CI, bxSites documentation in `docs/`\n","installs":1497,"entryID":"8a809c88a0ee50d301a0f37064120023","sourceURL":"https://github.com/ortus-boxlang/bx-playwright","hits":228,"numberOfRatings":"0","versions":[{"downloadURL":"https://downloads.ortussolutions.com/ortussolutions/boxlang-modules/bx-playwright/1.0.0-snapshot/bx-playwright-1.0.0-snapshot.zip","version":"1.0.0-snapshot","installs":1453,"binaryHash":"","sortOrder":1}],"isListed":true,"updatedDate":"2026-09-30T13:19:10-05:00","descriptionFormat":"md","bugsURL":"https://ortussolutions.atlassian.net/browse/BLMODULES","user":{"avatarLink":"//www.gravatar.com/avatar.php?gravatar_id=61532a7f32112e9fe23da5a1b5a9ef6a&s=80&r=PG","lname":"Solutions","twitterURL":"","fname":"Ortus","githubURL":"","jobTitle":"","linkedinURL":"","otherURL":"","aboutMe":"","facebookURL":"","organization":"","blogURL":"","fullName":"Ortus Solutions","username":"ortus"},"typeName":"BoxLang Modules","numberOfVersions":"1"},"error":false,"messages":[]}