To run Selenium tests in GitHub Actions, add a workflow YAML file under .github/workflows, choose the events that should start it, select a runner and browser setup, install the project’s pinned dependencies, run its existing test command, and save reports or failure screenshots as artifacts. The workflow structure is reusable; the setup and test commands must match your repository’s language and framework.
How a Selenium Actions workflow works
GitHub Actions workflows are YAML files in .github/workflows. A workflow responds to events, contains one or more jobs, and each job contains steps that run commands or actions. A Selenium job adds the browser environment and test invocation to that same structure. GitHub documents these workflow building blocks at About workflows.
- Choose triggers: decide whether tests run on pull requests, pushes, manual dispatch, a schedule, or a combination.
- Choose an execution environment: specify a GitHub-hosted runner such as Linux, Windows, or macOS, and decide which browser the tests need.
- Install and run the project: check out the code, set up the language runtime, install pinned dependencies, and invoke the test suite’s established command.
- Keep failure evidence: save test reports, logs, and screenshots so they remain accessible after the job ends.
GitHub-hosted jobs run in their own virtual machine or container. The Selenium WebDriver interface lets test code control browsers, but available browser installations depend on the selected runner image. Confirm the image contents and the browser/version requirements for your application rather than assuming a browser is preinstalled. See GitHub-hosted runners and Selenium’s WebDriver documentation.
Choose triggers and runner deliberately
Run on pull requests and pushes
Pull-request runs provide feedback while a change is under review; push runs can cover branch integration. Choose the events and branch filters that fit your repository’s workflow. These triggers are complementary: a scheduled run can detect periodic issues, but should not replace tests tied to code changes.
#1 Best Overall
Add manual or scheduled runs when useful
Manual dispatch is useful when a developer needs to start a workflow on demand. A schedule can run periodic checks. GitHub notes lifecycle behavior for scheduled workflows; for example, a deactivated scheduled workflow can be reactivated when a user with write permission changes its cron schedule. See Events that trigger workflows.
Select the OS and browser combination
Use a runner and browser combination that reflects the browser coverage you need. Selenium’s Python bindings document support for Chrome, Edge, Firefox, Safari, WebKitGTK, and WPEWebKit, but that does not mean each one is installed on every GitHub-hosted image. Check the current image documentation and provision a compatible browser and driver where needed. Selenium’s browser support details are in its browser documentation.
Illustrative workflow structure
This outline shows where the pieces belong, not a universally copy-ready Selenium setup. Add the runtime setup, dependency installation, and test command used by your repository. Confirm action versions and runner-image contents against the current documentation before adopting them.
Rank #2
name: Selenium tests
on:
pull_request:
push:
branches: [main]
jobs:
selenium:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
# Add the language setup and dependency installation used by this repo.
# Run the repository's Selenium test command here.
# Upload test reports and failure screenshots even when tests fail.The workflow uses GitHub’s checkout action as an example, but action and runtime choices should be maintained for your project. Pin dependencies where your package manager supports it so CI uses the versions recorded for the application rather than an unintended newer dependency.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Set up Selenium and run your existing tests
Python example: Selenium Manager
For modern Selenium Python bindings, Selenium Manager handles browser and driver installation or management in the common WebDriver flow. A basic Chrome setup can therefore create a driver without manually specifying a driver path:
from selenium import webdriver
def test_homepage_title():
driver = webdriver.Chrome()
try:
driver.get("https://example.com")
assert "Example Domain" in driver.title
finally:
driver.quit()This is a minimal illustration, not a complete test framework. Put the test in the structure your project already uses and run it with that framework’s command. Selenium Manager does not remove every environment concern: network restrictions, custom browser versions, unsupported platforms, and strict reproducibility requirements may call for explicit browser and driver provisioning. Consult the Selenium Manager documentation.
Adapt the installation and test steps to your repository
The correct commands depend on the language, package manager, and test framework. Add the project’s language setup action, install from its lockfile or equivalent pinned dependency record, then run the existing test command. The illustrative outline above intentionally does not guess those commands: no repository, language, framework, or target browser was specified.
Runner host or job container?
By default, steps run on the selected runner host unless an action runs in a container. You can also configure a job-level container with jobs.<job_id>.container. A container can standardize project dependencies, but its image still needs a compatible browser and system libraries, or a way to obtain them. GitHub documents the container model at Running jobs in a container; it does not prescribe a particular Selenium image.
The Tool Desk
Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →- Runner host: simpler when the chosen runner image already fits your setup; verify the image’s installed browser and dependencies.
- Job container: useful when you need a more controlled dependency environment; account for browser, driver, and system-library provisioning inside that environment.
Save reports, logs, and screenshots
Make diagnostic outputs available after a run. GitHub defines an artifact as “a file or collection of files produced during a workflow run.” Test results, failure output, and screenshots are useful artifacts, and uploaded artifacts remain available after the job completes subject to retention settings. See Store workflow data as artifacts.
- Configure the test suite to write reports and logs to known paths.
- Capture a browser screenshot when a test fails, ideally alongside the failing test’s name or other useful context.
- Upload the relevant files with failure-handling conditions appropriate to the current Actions syntax, so the upload step still runs when the test step fails.
- Use caching for reusable dependencies or intermediate files, not instead of preserving outputs needed to diagnose failures.
The exact artifact-upload action and its version are implementation choices; confirm the current GitHub documentation when adding it to your workflow.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Common problems and fixes
Browser or driver cannot be found
Cause: the chosen runner image or container does not contain the expected browser, or the browser and driver versions are incompatible. Fix: check the runner image documentation and the actual job environment, then provision a compatible browser/driver pair. Selenium Manager can simplify the standard Python flow, but may not suit network-restricted or tightly pinned environments.
WebDriver setup fails in a restricted environment
Cause: automatic browser or driver management cannot obtain what it needs, or the environment uses a custom browser version. Fix: provide the required browser and compatible driver explicitly, and confirm that the job can access any required downloads or internal package sources.
Quick wins for a faster PC:
Scan for outdated or missing drivers - takes under a minuteDriver Scan →Repair Windows errors before they cause bigger problemsFix Now →Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →A test passes locally but fails in CI
Cause: CI may use a different OS, browser, viewport, dependency set, or network environment from a developer workstation. Fix: compare those conditions, keep dependencies pinned, and inspect the saved report, logs, and failure screenshot before changing the test.
The job runs but no diagnostics remain
Cause: outputs were not written to the expected path, or the upload step was skipped after test failure. Fix: verify the test output directory and configure artifact upload to run under the appropriate failure condition.
A scheduled check stops running
Cause: scheduled workflows have lifecycle behavior tied to repository activity and permissions. Fix: check the workflow’s status and schedule configuration; GitHub documents cases where a write-permission user changing the cron schedule reactivates a deactivated schedule.
Or skip the browser setup
If your goal is to capture a page rather than exercise browser interactions and assertions, ScreenshotNeo offers a website screenshot API and MCP server. One GET request can return an image or PDF; it is not a replacement for Selenium tests that need to interact with an application.
Do these 3 things before closing this tab:
1Repair Windows errors before they cause bigger problems2Fix the driver behind crashes, sound loss and screen glitches3Clear out junk files and repair common Windows errorscurl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpSee the ScreenshotNeo API documentation. Cookie banners, popups, and chat widgets are removed before the shot; bot checks, blank pages, and failed loads are never billed. Its MCP server lets AI agents take screenshots. The free plan includes 1,000 screenshots a month with no card, and paid plans start at $5 for 3,000. Learn about ScreenshotNeo, or sign up for 1,000 free screenshots a month, with no card.
Frequently Asked Questions
Does a GitHub Actions Selenium workflow need to run on every push?
No. Configure pull-request, push, manual, or scheduled triggers to match the feedback and maintenance needs of your repository.
Can ScreenshotNeo replace Selenium for end-to-end tests?
No. ScreenshotNeo captures pages as images or PDFs; Selenium is the appropriate fit when tests must control a browser and verify interactions or application behavior.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
