bx-playwright: Browsing
BoxLang is the AI-native software productivity platform for building, modernizing and running applications, with developers and AI agents working together.
Entry Points
pw = playwright( { baseURL : "http://localhost:8080" } ) // nothing starts yet
page = pw.visit( "/login" ) // new context + page + navigation
page = pw.newPage( { colorScheme : "dark" } ) // context-level overrides
ctx = pw.newContext( { locale : "es-ES" } ) // isolated cookies/storage
page = ctx.newPage()
// Scoped: pages and (if new) the manager are closed afterwards
playwright().browse( ( page ) => page.visit( "https://boxlang.io" ).assertSee( "BoxLang" ) )
playwright().browse( ( alice, bob ) => { /* one isolated page per argument */ } )
Cleanup: page.close() closes the page and its context; page.quit() / pw.close() close everything. A manager must stay on the thread that created it.
Smart Selectors
| Selector |
Finds |
@name |
[data-testid=name] or a page object alias |
#id, .class, input[name=email], ul li, h1 |
CSS (lowercase tag names only) |
//div, css=, xpath=, text=, role=button[name="Save"] |
Playwright selectors |
ref=e12 |
Element ref from an AI snapshot |
| anything else |
Visible text: fill() tries label, placeholder, then name; click() tries button or link name, then exact text |
page.visit( "/login" )
.fill( "Email", "luis@ortus.com" ) // label
.fill( "Password", "secret" ) // placeholder
.check( "Remember me" )
.select( "@role", "editor" )
.click( "Sign in" )
Actions (all chainable)
click( sel, options ), dblclick, hover, focus, fill( sel, value ), type( sel, text, delay ), clear, press( key ) or press( sel, key ), check, uncheck, select( sel, valueOrArray ), upload( sel, pathOrArray ), drag( from, to ), scrollTo, visit( url, options ), back(), forward(), reload(), setContent( html ).
On a Locator the selector is optional: page.byLabel( "Email" ).fill( "a@b.com" ), page.locator( "#q" ).press( "Enter" ).
Finders and Locators
page.byRole( "button", { name : "Save" } ).click()
page.byText( "Welcome" )
page.byLabel( "Email" ); page.byPlaceholder( "Search" ); page.byTestId( "cart" ); page.byAltText( "Logo" ); page.byTitle( "Help" )
page.frame( "#payment" ).fill( "Card number", "4242..." )
todos = page.locator( ".todos li" )
todos.count() // no waiting
todos.texts() // array of strings
todos.nth( 2 ).text() // 1-based!
todos.first(); todos.last(); todos.visible()
todos.filter( { hasText : "Ship" } ).click()
todos.all().each( ( item ) => println( item.text() ) )
page.within( "@cart", ( cart ) => cart.click( "Remove" ).assertSee( "Empty" ) )
Reading and Waiting
url(), title(), content(), text( sel ), html( sel ), value( sel ), attribute( sel, name ), isVisible( sel ), evaluate( js, arg ).
Actions and assertions auto-wait. Explicit waits: waitFor( sel, "visible|hidden|attached|detached" ), waitForText( text ), waitForUrl( urlOrGlobOrRegex ), waitForLoadState( "networkidle" ), wait( ms ) (last resort).
popup = page.waitForPopup( () => page.click( "Open report" ) )
file = page.waitForDownload( () => page.click( "Export" ), "export.csv" ) // { path, suggestedFilename, url }
evaluate() calls function strings: use "() => { statements }" for statements, "document.title" for expressions.
Emulation
page.setViewport( 500, 400 ), page.emulate( { colorScheme : "dark", media : "print" } ), page.freezeTime( "2030-05-01T10:00:00" ), page.clock().
Discover
page.help(), page.help( "fill" ), playwright().help() list every method with arguments from the docblocks. getJava() returns the raw Playwright object.
Automation Scripts
bx-playwright also runs plain BoxLang jobs outside of tests. Full guide: docs/automation.md (bxplaywright.boxlang.io/automation/).
// jobs/capture.bxs, run with: boxlang jobs/capture.bxs --url=https://boxlang.io --out=home.png
args = cliGetArgs() // { options : { url, out }, positionals : [ "jobs/capture.bxs", ... ] }
playwright( "ci" ).browse( ( page ) => { // browse() closes everything, even on errors
page.visit( args.options.url ).screenshot( args.options.out ?: "capture.png", { fullPage : true } )
} )
- Record instead of writing clicks:
bxplaywright codegen <url> --output=job.bxs, then rewrite // TODO translate: lines, move secrets to getSystemSetting(), add assertions after key steps.
- Log in once:
pw.session( "app", ( page ) => ...login..., { maxAge : 720 } ), then pw.browse( fn, { session : "app" } ).
browse() returns the callback result: scrape with page.locator( "tr" ).all().map( ( row ) => row.locator( "td" ).texts() ), write with fileWrite( path, jsonSerialize( data ) ).
- Retry flaky sites by catching
Playwright.Timeout in a loop; fail a job with cliExit( 1 ) (an uncaught error also exits 1).
- The
ci profile is headless and keeps a screenshot, trace and video of a failed browse().
- Servers:
bxplaywright install chromium --with-deps once, then boxlang job.bxs from cron.
- BoxLang scheduler: a class with
configure() calling scheduler.task( "name" ).call( () => playwright( "ci" ).browse( ... ) ).everyHour(), run with boxlang schedule Scheduler.bx. Use absolute paths for files (relative ones resolve against the scheduler file) and yyyy-MM-dd date masks (mm is minutes). One browser per task run: Playwright is not thread safe.
1---2name: bx-playwright-browsing3description: "Use this skill when driving a browser from BoxLang with bx-playwright: the playwright() BIF, visit(), browse(), newPage()/newContext(), smart selectors (@testId, CSS, visible text), chainable actions (click, fill, check, select, press, upload), finders (byRole, byText, byLabel), locators (nth, filter, texts), within(), frames, waiting, popups, downloads, evaluate, and cleanup., and automation scripts (.bxs jobs with cliGetArgs(), codegen recording, retries, exit codes, cron or boxlang schedule)"4metadata:5 source: https://skillmd.com/skills/ortus-boxlang/bx-playwright-browsing6---78# bx-playwright: Browsing910> BoxLang is the AI-native software productivity platform for building, modernizing and running applications, with developers and AI agents working together.1112## Entry Points1314```js15pw = playwright( { baseURL : "http://localhost:8080" } ) // nothing starts yet16page = pw.visit( "/login" ) // new context + page + navigation17page = pw.newPage( { colorScheme : "dark" } ) // context-level overrides18ctx = pw.newContext( { locale : "es-ES" } ) // isolated cookies/storage19page = ctx.newPage()2021// Scoped: pages and (if new) the manager are closed afterwards22playwright().browse( ( page ) => page.visit( "https://boxlang.io" ).assertSee( "BoxLang" ) )23playwright().browse( ( alice, bob ) => { /* one isolated page per argument */ } )24```2526Cleanup: `page.close()` closes the page and its context; `page.quit()` / `pw.close()` close everything. A manager must stay on the thread that created it.2728## Smart Selectors2930| Selector | Finds |31|---|---|32| `@name` | `[data-testid=name]` or a page object alias |33| `#id`, `.class`, `input[name=email]`, `ul li`, `h1` | CSS (lowercase tag names only) |34| `//div`, `css=`, `xpath=`, `text=`, `role=button[name="Save"]` | Playwright selectors |35| `ref=e12` | Element ref from an AI snapshot |36| anything else | Visible text: `fill()` tries label, placeholder, then name; `click()` tries button or link name, then exact text |3738```js39page.visit( "/login" )40 .fill( "Email", "luis@ortus.com" ) // label41 .fill( "Password", "secret" ) // placeholder42 .check( "Remember me" )43 .select( "@role", "editor" )44 .click( "Sign in" )45```4647## Actions (all chainable)4849`click( sel, options )`, `dblclick`, `hover`, `focus`, `fill( sel, value )`, `type( sel, text, delay )`, `clear`, `press( key )` or `press( sel, key )`, `check`, `uncheck`, `select( sel, valueOrArray )`, `upload( sel, pathOrArray )`, `drag( from, to )`, `scrollTo`, `visit( url, options )`, `back()`, `forward()`, `reload()`, `setContent( html )`.5051On a Locator the selector is optional: `page.byLabel( "Email" ).fill( "a@b.com" )`, `page.locator( "#q" ).press( "Enter" )`.5253## Finders and Locators5455```js56page.byRole( "button", { name : "Save" } ).click()57page.byText( "Welcome" )58page.byLabel( "Email" ); page.byPlaceholder( "Search" ); page.byTestId( "cart" ); page.byAltText( "Logo" ); page.byTitle( "Help" )59page.frame( "#payment" ).fill( "Card number", "4242..." )6061todos = page.locator( ".todos li" )62todos.count() // no waiting63todos.texts() // array of strings64todos.nth( 2 ).text() // 1-based!65todos.first(); todos.last(); todos.visible()66todos.filter( { hasText : "Ship" } ).click()67todos.all().each( ( item ) => println( item.text() ) )6869page.within( "@cart", ( cart ) => cart.click( "Remove" ).assertSee( "Empty" ) )70```7172## Reading and Waiting7374`url()`, `title()`, `content()`, `text( sel )`, `html( sel )`, `value( sel )`, `attribute( sel, name )`, `isVisible( sel )`, `evaluate( js, arg )`.7576Actions and assertions auto-wait. Explicit waits: `waitFor( sel, "visible|hidden|attached|detached" )`, `waitForText( text )`, `waitForUrl( urlOrGlobOrRegex )`, `waitForLoadState( "networkidle" )`, `wait( ms )` (last resort).7778```js79popup = page.waitForPopup( () => page.click( "Open report" ) )80file = page.waitForDownload( () => page.click( "Export" ), "export.csv" ) // { path, suggestedFilename, url }81```8283`evaluate()` calls function strings: use `"() => { statements }"` for statements, `"document.title"` for expressions.8485## Emulation8687`page.setViewport( 500, 400 )`, `page.emulate( { colorScheme : "dark", media : "print" } )`, `page.freezeTime( "2030-05-01T10:00:00" )`, `page.clock()`.8889## Discover9091`page.help()`, `page.help( "fill" )`, `playwright().help()` list every method with arguments from the docblocks. `getJava()` returns the raw Playwright object.9293## Automation Scripts9495bx-playwright also runs plain BoxLang jobs outside of tests. Full guide: `docs/automation.md` (bxplaywright.boxlang.io/automation/).9697```js98// jobs/capture.bxs, run with: boxlang jobs/capture.bxs --url=https://boxlang.io --out=home.png99args = cliGetArgs() // { options : { url, out }, positionals : [ "jobs/capture.bxs", ... ] }100playwright( "ci" ).browse( ( page ) => { // browse() closes everything, even on errors101 page.visit( args.options.url ).screenshot( args.options.out ?: "capture.png", { fullPage : true } )102} )103```104105- Record instead of writing clicks: `bxplaywright codegen <url> --output=job.bxs`, then rewrite `// TODO translate:` lines, move secrets to `getSystemSetting()`, add assertions after key steps.106- Log in once: `pw.session( "app", ( page ) => ...login..., { maxAge : 720 } )`, then `pw.browse( fn, { session : "app" } )`.107- `browse()` returns the callback result: scrape with `page.locator( "tr" ).all().map( ( row ) => row.locator( "td" ).texts() )`, write with `fileWrite( path, jsonSerialize( data ) )`.108- Retry flaky sites by catching `Playwright.Timeout` in a loop; fail a job with `cliExit( 1 )` (an uncaught error also exits 1).109- The `ci` profile is headless and keeps a screenshot, trace and video of a failed `browse()`.110- Servers: `bxplaywright install chromium --with-deps` once, then `boxlang job.bxs` from cron.111- BoxLang scheduler: a class with `configure()` calling `scheduler.task( "name" ).call( () => playwright( "ci" ).browse( ... ) ).everyHour()`, run with `boxlang schedule Scheduler.bx`. Use absolute paths for files (relative ones resolve against the scheduler file) and `yyyy-MM-dd` date masks (`mm` is minutes). One browser per task run: Playwright is not thread safe.