# Playwright browser automation

Playwright is a browser-automation library. Connect uses it for two things. On the production host it renders pages built entirely in JavaScript when the prospect research engine reads a public website. In development it opens Connect's own screens, as the Owner and as a customer, at several widths, to check what a person actually sees.

- **Status:** Reference
- **Audience:** both, developer
- **Last verified:** 2026-11-02
- **Canonical:** https://connectbyjbrh.com/docs/technology/playwright/

## What it is

Playwright was released by Microsoft in 2020. One API drives Chromium, Firefox and WebKit, with auto-waiting and isolated browser contexts. The Python package bundles a driver and fetches matching browser builds.

Connect keeps it out of the web application's main requirements. It lives in `requirements-research.txt`, so the application runs without it. A JavaScript-only page is then read as the server sends it, and the Sources screen says so.

**Category** — Browser automation
**Version in Connect** — `playwright==1.63.0` (exact, `requirements-research.txt`)
**Browser on the host** — The Chromium headless shell, under its own AppArmor profile
**Official site** — [playwright.dev](https://playwright.dev/python/)

## Where Connect uses it

| Place in Connect | What it does there |
|---|---|
| `backend/app/prospect_web.py` | Renders a public page when the research engine needs its JavaScript output |
| `tools/ui_gate.py` | Boots this checkout and checks the changed screens for both audiences, from 320 to 1440 px, at 200 % zoom |
| `tools/test_*_browser*.py` | Browser suites, such as the softphone and the visitor assistant |

## How it connects

1. The research engine decides a page needs rendering
2. A sandboxed headless Chromium loads it
3. Playwright waits for the content and reads the text
4. The page is closed. Nothing is submitted, and no sign-in is attempted
5. The text joins the research with its source address

## Benefits and limits

What it gives Connect:

- Reads modern sites that ship an empty HTML shell.
- The same tool checks Connect's own screens, so the gates see what a person sees.
- Optional: if it is missing, the research engine reads the plain page instead of failing.

Where it stops, and what Connect does about it:

- A browser is heavy. Rendering is used only when plain fetching is not enough.
- It does not get past sign-in walls or bot checks, and Connect does not try to.
- The exact pin means an upgrade is deliberate. A new version needs its matching browser build.

## Security and privacy

- Chromium runs sandboxed under an AppArmor profile, as an unprivileged user.
- Research reads public pages only. No credentials, no form submission, no driven account sessions (marketplace access uses official APIs instead).
- In tests it uses minted preview sessions against a `_test` database, never production.

## Licence, cost and versions

| Question | Answer |
|---|---|
| Licence | Apache-2.0 (browsers carry their own licences) |
| Cost | None |
| Version | `playwright==1.63.0` |
| Compatibility | Its matching Chromium build; Ubuntu 24.04 needs the system libraries the install step lists |

## Troubleshooting

**Research shows a near-empty page** — Playwright is not installed on the host, or rendering failed. The Sources screen states which.
**Browser fails to launch** — Missing system libraries or the sandbox profile. See the research engine's host notes.
**A UI gate run fails in seconds** — Usually an expired preview session or a path problem. Fix it on two views before a long run.

## Official references

- [Playwright for Python](https://playwright.dev/python/docs/intro)
- [Browsers and dependencies](https://playwright.dev/python/docs/browsers)
- [Release notes](https://playwright.dev/python/docs/release-notes)

## Questions

### Does Connect use Playwright to log in to marketplaces or social networks?

No. Marketplaces and social platforms are reached only through their official APIs and the business's own authorisation. Never a driven browser, and never a stored password.

### Is a screenshot from a test a production result?

No. It shows how a screen renders against test data. Production behaviour is proven by production evidence.

## Related

- [Web accessibility](https://connectbyjbrh.com/docs/technology/accessibility/)
- [Development and quality tools](https://connectbyjbrh.com/docs/technology/dev-tooling/)
- [robots.txt](https://connectbyjbrh.com/docs/technology/robots-txt/)
- [Content Security Policy](https://connectbyjbrh.com/docs/technology/csp/)

## What this page is based on

- `requirements-research.txt`
- `backend/app/prospect_web.py`
- `tools/ui_gate.py`
- `docs/infrastructure/AWS-HOST.md`
