Skip to content

usage.md

Latest commit

 

History

History
125 lines (95 loc) · 4.92 KB

usage.md

File metadata and controls

125 lines (95 loc) · 4.92 KB
Raw

Usage

This assumes you've already run browser.cmd build once (see the Installation section of the README).

Starting a farm

browser.cmd start 1              # one Chromium browser (env default), for quick manual testing
browser.cmd start 10             # ten Chromium browsers, for a parallel test run
browser.cmd start 5 firefox      # five Firefox browsers, overriding env for this batch only

Each numbered instance gets its own container (rb-1 … rb-N), its own VNC port (590N), its own noVNC port (608N), and its own logs/rb-N/ and downloads/rb-N/ folder on the host. Running start again with a smaller N than what's already running is safe — existing containers are left alone ([SKIP] is printed for each one already up); it does not stop the extras. Use stop first if you want an exact count.

Every container in one start batch gets the same browser engine. To run different engines side by side, start them in separate batches (they'll use different rb-N slots automatically as long as the earlier batch's containers are still running) — see examples/custom-single-container.md for a fully manual per-container override if you need mixed engines within what would otherwise be one batch.

Checking what's running

browser.cmd status    # docker ps table, filtered to this farm
browser.cmd list      # Eggplant-ready connection table (host/port/password)
browser.cmd health    # per-container Docker healthcheck status

list is the one to paste into an Eggplant "Add SUT" dialog or a test runner config — it already has the port arithmetic done for you.

Watching a container

browser.cmd logs 3     # tail -f equivalent, Ctrl+C to stop watching
browser.cmd shell 3    # interactive bash inside container rb-3

Inside a shell, useful checks:

DISPLAY=:1 xdpyinfo | grep dimensions     # confirm actual virtual display size
pgrep -fa "$BROWSER"                      # confirm the selected browser is actually running
cat /logs/startup.log                     # full startup sequence log
cat /logs/browser.log                     # the browser process's own stdout/stderr

Viewing a browser without a VNC client

Open http://localhost:6081/vnc.html (for rb-1; 6082 for rb-2, etc.) in any browser on the host. This is the noVNC web portal — full mouse/keyboard control, no client software needed. Useful for eyeballing what a test is about to see, independent of Eggplant.

Connecting from Eggplant Functional

Add SUT → Type: VNC → Host: localhost → Port: 5900 + N → Password: whatever VNC_PASS is set to in env. See examples/eggplant-sut.md for a filled-in example.

Automation integration (Playwright / Selenium)

Every container is a plain VNC target — Eggplant isn't the only thing that can drive it. See examples/playwright-automation.md and examples/selenium-automation.md for connecting a Playwright or Selenium script to a running container's noVNC/VNC endpoint (useful for visually observing an automated run, or for driving the browser through the container's exposed debugging port where the engine supports one).

Restarting for a clean state

Because SESSION_MODE=fresh wipes the browser's profile on every container start (not on every page load), the way to get a genuinely clean browser mid-test-run is to recycle the container, not just navigate away:

browser.cmd restart 5     # stop everything, start 5 fresh containers

or, to reset a single instance without touching the others:

docker rm -f rb-3
browser.cmd start 3

(browser.cmd doesn't have a single-instance restart subcommand — the two commands above are the equivalent. See examples/ for a scripted version.)

Stopping everything

browser.cmd stop

Removes every rb-* container. Bind-mounted logs/ and downloads/ folders on the host are left in place (they're gitignored, not deleted) so you can inspect them after the fact.

Persistent sessions (keeping logins across restarts)

Set SESSION_MODE=persistent in env, then browser.cmd start. Each container's profile is bind-mounted at profiles/rb-N/ on the host (mounted to /data/profile in the container), and namespaced by engine inside that —profiles/rb-N/chromium/, profiles/rb-N/firefox/, etc. — so it survives docker rm / browser.cmd restart, and switching BROWSER for the same instance number never mixes one engine's profile into another's. Delete the relevant profiles/rb-N/<browser>/ folder (or run browser.cmd stop and remove it manually) to force a clean profile for that instance again.

fresh mode (the default) ignores profiles/ entirely — the profile lives at /tmp/<browser>-profile inside the container and is wiped on every container start.