Running Vibium in CI/CD with GitHub Actions

To run Vibium in CI/CD with GitHub Actions, add a workflow that installs vibium with pip, runs your tests headless, and uploads screenshots or traces as artifacts on failure. Vibium ships as a single Go binary that auto-downloads Chrome for Testing on first run, so the runner has no driver to install and no browser version to align — the classic cause of flaky CI in older tools. On ubuntu-latest you install Chrome's shared system libraries (libnss3, libgbm1, libasound2, and friends), pip install vibium, set HEADLESS=true, and run pytest. Because Vibium's find() auto-waits for actionability, the same suite that passes locally passes on a slower CI runner without sprinkled sleep() calls. Add an artifact-upload step for failure screenshots — or a Vibium trace — and you get a fast, debuggable pipeline that runs on every push and pull request.

What is the minimal GitHub Actions workflow?

Drop this file at .github/workflows/vibium.yml. It checks out your code, sets up Python, installs Chrome's libraries and Vibium, then runs the suite headless.

name: Vibium tests
 
on:
  push:
  pull_request:
 
jobs:
  test:
    runs-on: ubuntu-latest
    env:
      HEADLESS: "true"
    steps:
      - uses: actions/checkout@v4
 
      - uses: actions/setup-python@v5
        with:
          python-version: "3.12"
 
      - name: Install Chrome system libraries
        run: |
          sudo apt-get update
          sudo apt-get install -y \
            libnss3 libatk-bridge2.0-0 libgbm1 libasound2 \
            libxkbcommon0 libxcomposite1 libxdamage1 libxfixes3 \
            libxrandr2 libdrm2 libpango-1.0-0 libcairo2
 
      - name: Install Vibium
        run: |
          pip install vibium pytest
          vibium install   # pre-download Chrome for Testing
 
      - name: Run tests
        run: pytest -v

The HEADLESS: "true" environment variable is read by the browser fixture so Chrome runs without a display. vibium install pre-fetches Chrome during the job so the first test does not pay the download cost.

Why is there no driver or browser to install?

Vibium bundles its WebDriver BiDi engine into one Go binary and downloads a known-good Chrome for Testing itself, so there is nothing to version-match. In older stacks, CI broke constantly because the installed browser drifted out of sync with the driver. Vibium removes that whole class of failure: the only host setup is Chrome's shared libraries, which the OS provides, and modern headless Chrome renders with no X display, so you do not need Xvfb. For the architecture behind this, see how Vibium works.

How does my code know to run headless in CI?

Read headless mode from an environment variable in your launch code so the identical suite runs headed locally and headless in CI. This is the single switch the workflow above flips.

import os
from vibium import browser_sync as browser
 
headless = os.getenv("HEADLESS", "false") == "true"
vibe = browser.launch(headless=headless)

With this pattern, you debug headed on your laptop, push, and the same code runs invisibly on the runner — no separate CI code path to drift out of sync. Centralizing it in a fixture (see structuring a Vibium suite) keeps every test consistent.

How do I capture screenshots and traces on failure?

Since CI runs are headless and remote, a failure screenshot is the fastest way to see what the page actually showed. Save a PNG when a test fails and let the workflow upload it. Vibium's screenshot() returns PNG bytes, so writing it to disk is one line.

import pytest
from vibium import browser_sync as browser
 
 
@pytest.fixture
def vibe(request):
    instance = browser.launch(headless=True)
    yield instance
    if request.node.rep_call.failed:
        png = instance.screenshot(full_page=True)
        with open(f"fail-{request.node.name}.png", "wb") as f:
            f.write(png)
    instance.quit()

Then add an upload step to the workflow so the artifacts survive the run:

      - name: Upload failure screenshots
        if: failure()
        uses: actions/upload-artifact@v4
        with:
          name: vibium-screenshots
          path: "fail-*.png"

For richer debugging, record a Vibium trace with screenshots and DOM snapshots, upload the resulting trace.zip the same way, and open it in the Vibium Trace viewer to scrub the timeline frame by frame. See taking a full-page screenshot for the capture options.

How do I cache Chrome to speed up CI?

Vibium downloads Chrome for Testing once and reuses it, so caching that download trims a few seconds off every run. Cache Vibium's browser directory between jobs with actions/cache, keyed on your Vibium version, and the vibium install step becomes a near-instant cache hit. This matters most on large monorepos where the workflow fires on every commit. Combined with running your suite in parallel — covered in parallelizing Vibium tests — caching keeps total pipeline time low even as the test count climbs.

Why is Vibium a clean fit for CI/CD?

Three design choices make Vibium pipelines low-maintenance. First, the single Go binary plus auto-downloaded Chrome means zero driver management. Second, headless is a launch flag, not a separate code path, so the suite you debug is byte-for-byte the suite that runs in CI. Third, auto-waiting find() keeps tests stable on slower shared runners without manual sleeps. Together they remove the three things that most often break browser jobs — driver drift, headless quirks, and timing flakiness — leaving you a pipeline that just runs pytest.

Next steps

• How to Structure a Vibium Test Suite
• How to Parallelize Vibium Tests
• How Vibium Works: BiDi, the Go Binary, and MCP