Convert Figma logo to code with AI

SeleniumHQ logoselenium

A browser automation framework and ecosystem.

30,175
8,100
30,175
243
View on GitHubView on NPM

Top Related Projects

microsoft's avatar

playwright

65,491

Playwright is a framework for Web Testing and Automation. It allows testing Chromium, Firefox and WebKit with a single API.

cypress-io's avatar

cypress

46,661

Fast, easy and reliable testing for anything that runs in a browser.

puppeteer's avatar

puppeteer

88,205

JavaScript API for Chrome and Firefox

appium's avatar

appium

18,634

Cross-platform automation framework for all kinds of apps, built on top of the W3C WebDriver protocol

webdriverio's avatar

webdriverio

8,960

Next-gen browser and mobile automation test framework for Node.js

Quick Overview

Selenium is a powerful open-source tool for automating web browsers. It provides a suite of tools for browser automation that supports multiple programming languages and browsers, making it widely used for web application testing and web scraping tasks.

Pros

  • Cross-browser compatibility (supports Chrome, Firefox, Safari, Edge, etc.)
  • Supports multiple programming languages (Java, Python, C#, Ruby, JavaScript, etc.)
  • Large and active community, providing extensive documentation and support
  • Integrates well with various testing frameworks and CI/CD tools

Cons

  • Can be slow for large-scale testing compared to headless browsers
  • Setup and configuration can be complex for beginners
  • Occasional stability issues, especially with browser updates
  • Limited support for handling dynamic web elements without additional libraries

Code Examples

  1. Opening a web page and getting the title:
from selenium import webdriver
from selenium.webdriver.chrome.service import Service
from webdriver_manager.chrome import ChromeDriverManager

driver = webdriver.Chrome(service=Service(ChromeDriverManager().install()))
driver.get("https://www.example.com")
print(driver.title)
driver.quit()
  1. Filling out a form and submitting:
from selenium import webdriver
from selenium.webdriver.common.by import By
from selenium.webdriver.chrome.service import Service
from webdriver_manager.chrome import ChromeDriverManager

driver = webdriver.Chrome(service=Service(ChromeDriverManager().install()))
driver.get("https://www.example.com/form")

driver.find_element(By.ID, "username").send_keys("myusername")
driver.find_element(By.ID, "password").send_keys("mypassword")
driver.find_element(By.ID, "submit").click()

driver.quit()
  1. Waiting for an element to be visible:
from selenium import webdriver
from selenium.webdriver.common.by import By
from selenium.webdriver.support.ui import WebDriverWait
from selenium.webdriver.support import expected_conditions as EC
from selenium.webdriver.chrome.service import Service
from webdriver_manager.chrome import ChromeDriverManager

driver = webdriver.Chrome(service=Service(ChromeDriverManager().install()))
driver.get("https://www.example.com")

element = WebDriverWait(driver, 10).until(
    EC.presence_of_element_located((By.ID, "myDynamicElement"))
)

driver.quit()

Getting Started

To get started with Selenium in Python:

  1. Install Selenium and WebDriver Manager:

    pip install selenium webdriver-manager

  2. Create a new Python file and import the necessary modules:

    from selenium import webdriver
from selenium.webdriver.chrome.service import Service
from webdriver_manager.chrome import ChromeDriverManager

  3. Initialize the WebDriver and navigate to a website:

    driver = webdriver.Chrome(service=Service(ChromeDriverManager().install()))
driver.get("https://www.example.com")

  4. Perform actions and assertions as needed, then close the browser:

    # Your test code here
driver.quit()

Competitor Comparisons

microsoft logo

playwright

65,491

Playwright is a framework for Web Testing and Automation. It allows testing Chromium, Firefox and WebKit with a single API.

Pros of Playwright

  • Auto-wait functionality for elements to be ready, reducing flaky tests
  • Built-in support for multiple browsers (Chromium, Firefox, WebKit) with a single API
  • Faster execution due to its architecture and efficient use of browser capabilities

Cons of Playwright

  • Smaller community and ecosystem compared to Selenium's mature environment
  • Limited language support (primarily JavaScript/TypeScript, with Python and .NET)
  • Steeper learning curve for those already familiar with Selenium

Code Comparison

Playwright:

const { chromium } = require('playwright');

(async () => {
  const browser = await chromium.launch();
  const page = await browser.newPage();
  await page.goto('https://example.com');
  await browser.close();
})();

Selenium:

from selenium import webdriver

driver = webdriver.Chrome()
driver.get('https://example.com')
driver.quit()

Both Playwright and Selenium are powerful tools for browser automation and testing. Playwright offers modern features and cross-browser support out of the box, while Selenium benefits from a larger ecosystem and broader language support. The choice between them depends on specific project requirements and team expertise.

cypress-io logo

cypress

46,661

Fast, easy and reliable testing for anything that runs in a browser.

Pros of Cypress

  • Faster test execution and setup due to its architecture
  • Built-in automatic waiting and retry-ability, reducing flaky tests
  • Comprehensive debugging tools and real-time reloading

Cons of Cypress

  • Limited cross-browser support (primarily focuses on Chrome-based browsers)
  • Cannot interact with multiple browser tabs or windows
  • Less suitable for testing non-web applications

Code Comparison

Selenium (Java):

WebDriver driver = new ChromeDriver();
driver.get("https://example.com");
WebElement element = driver.findElement(By.id("submit"));
element.click();
Assert.assertTrue(driver.getTitle().contains("Success"));

Cypress (JavaScript):

cy.visit('https://example.com')
cy.get('#submit').click()
cy.title().should('contain', 'Success')

Cypress offers a more concise syntax and built-in assertions, while Selenium requires more setup and explicit waits. Cypress's chain-of-command structure makes tests more readable, but Selenium's flexibility allows for testing across various browsers and platforms. Both tools have their strengths, and the choice depends on specific project requirements and team preferences.

puppeteer logo

puppeteer

88,205

JavaScript API for Chrome and Firefox

Pros of Puppeteer

  • Built specifically for Chrome/Chromium, offering deeper integration and better performance
  • Simpler API and easier setup, especially for JavaScript developers
  • Built-in support for generating PDFs and screenshots

Cons of Puppeteer

  • Limited to Chrome/Chromium browsers, lacking cross-browser support
  • Newer project with a smaller ecosystem compared to Selenium
  • May require more manual handling for certain scenarios (e.g., file uploads)

Code Comparison

Puppeteer:

const browser = await puppeteer.launch();
const page = await browser.newPage();
await page.goto('https://example.com');
await page.screenshot({path: 'screenshot.png'});
await browser.close();

Selenium (JavaScript):

const driver = await new Builder().forBrowser('chrome').build();
await driver.get('https://example.com');
await driver.takeScreenshot().then(
  (image) => fs.writeFileSync('screenshot.png', image, 'base64')
);
await driver.quit();

Both Puppeteer and Selenium are powerful tools for browser automation, but they cater to different needs. Puppeteer excels in Chrome-specific tasks and offers a more streamlined experience for JavaScript developers. Selenium, on the other hand, provides broader browser support and a more extensive ecosystem, making it suitable for cross-browser testing and more complex automation scenarios.

appium logo

appium

18,634

Cross-platform automation framework for all kinds of apps, built on top of the W3C WebDriver protocol

Pros of Appium

  • Supports mobile app testing (iOS, Android) in addition to web browsers
  • Allows testing of native, hybrid, and mobile web apps
  • Uses a single API for both iOS and Android, simplifying cross-platform testing

Cons of Appium

  • Slower test execution compared to Selenium for web testing
  • More complex setup and configuration, especially for mobile device testing
  • Less mature ecosystem and community support than Selenium

Code Comparison

Selenium (Python):

from selenium import webdriver

driver = webdriver.Chrome()
driver.get("https://www.example.com")
element = driver.find_element_by_id("search")
element.send_keys("test")
element.submit()

Appium (Python):

from appium import webdriver

desired_caps = {
    'platformName': 'Android',
    'deviceName': 'Android Emulator',
    'app': '/path/to/app.apk'
}
driver = webdriver.Remote('http://localhost:4723/wd/hub', desired_caps)
element = driver.find_element_by_id("search")
element.send_keys("test")
element.submit()

Both Selenium and Appium use similar syntax for web automation, but Appium requires additional configuration for mobile testing. Selenium is primarily focused on web browser automation, while Appium extends similar functionality to mobile app testing across platforms.

webdriverio logo

webdriverio

8,960

Next-gen browser and mobile automation test framework for Node.js

Pros of WebdriverIO

  • More modern JavaScript-based architecture, supporting async/await out of the box
  • Rich ecosystem of plugins and services for easier integration with various tools
  • Built-in test runner with parallel execution capabilities

Cons of WebdriverIO

  • Smaller community compared to Selenium, potentially leading to fewer resources and third-party integrations
  • Steeper learning curve for developers not familiar with Node.js ecosystem

Code Comparison

Selenium (Java):

WebDriver driver = new ChromeDriver();
driver.get("https://www.example.com");
WebElement element = driver.findElement(By.id("search"));
element.sendKeys("test");
element.submit();

WebdriverIO (JavaScript):

await browser.url('https://www.example.com');
const searchInput = await $('#search');
await searchInput.setValue('test');
await searchInput.keys('Enter');

Both Selenium and WebdriverIO are powerful tools for browser automation and testing. Selenium has a longer history and wider language support, while WebdriverIO offers a more modern approach with its JavaScript-based architecture. The choice between the two often depends on the specific project requirements, team expertise, and integration needs.

Convert Figma logo designs to code with AI

Visual Copilot

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot

README

Selenium

CI

Selenium Logo

Selenium is an umbrella project encapsulating a variety of tools and libraries enabling web browser automation. Selenium specifically provides an infrastructure for the W3C WebDriver specification — a platform and language-neutral coding interface compatible with all major web browsers.

The project is made possible by volunteer contributors who've generously donated thousands of hours in code development and upkeep.

Selenium's source code is made available under the Apache 2.0 license.

This README is for developers interested in contributing to the project. For people looking to get started using Selenium, please check out our User Manual for detailed examples and descriptions, and if you get stuck, there are several ways to Get Help.

Contributing

Please read CONTRIBUTING.md before submitting your pull requests.

Installing

These are the requirements to create your own local dev environment to contribute to Selenium.

All Platforms

  • Bazelisk, a Bazel wrapper that automatically downloads the version of Bazel specified in .bazelversion file and transparently passes through all command-line arguments to the real Bazel binary.
  • Java JDK version 17 or greater (e.g., Java 17 Temurin)
    • Set JAVA_HOME environment variable to location of Java executable (the JDK not the JRE)
    • To test this, try running the command javac. This command won't exist if you only have the JRE installed. If you're met with a list of command-line options, you're referencing the JDK properly.

MacOS

  • Xcode including the command-line tools. Install the latest version using: xcode-select --install
  • Rosetta for Apple Silicon Macs. Add build --host_platform=//:rosetta to the .bazelrc.local file. We are working to make sure this isn't required in the long run.

Windows

Several years ago Jim Evans published a great article on Setting Up a Windows Development Environment for the Selenium .NET Language Bindings; This article is out of date, but it includes more detailed descriptions and screenshots that some people might find useful.

Click to see Current Windows Setup Requirements

Option 1: Automatic Installation from Scratch

This script will ensure a complete ready to execute developer environment. (nothing is installed or set that is already present unless otherwise prompted)

  1. Open Powershell as an Administrator
  2. Execute: Set-ExecutionPolicy Bypass -Scope Process -Force to allow running the script in the process
  3. Navigate to the directory you want to clone Selenium in, or the parent directory of an already cloned Selenium repo
  4. Download and execute this script in the powershell terminal: [scripts/dev-environment-setup.ps1]`

Option 2: Manual Installation

  1. Allow running scripts in Selenium in general: 
    Set-ExecutionPolicy -ExecutionPolicy RemoteSigned
  2. Enable Developer Mode: 
    reg add "HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\AppModelUnlock" /t REG_DWORD /f /v "AllowDevelopmentWithoutDevLicense" /d "1"
  3. Install MSYS2, which is an alternative shell environment that provides Unix-like commands
    • Add bin directory to PATH environment variable (e.g., "C:\tools\msys64\usr\bin")
    • Add bash.exe location as the BAZEL_SH environment variable (e.g., "C:\tools\msys64\usr\bin\bash.exe")
  4. Install the latest version of Visual Studio Community
    • Use the visual studio installer to modify and add the "Desktop development with C++" Workload
    • Add Visual C++ build tools installation directory location to BAZEL_VC environment variable (e.g. "C:\Program Files\Microsoft Visual Studio\2022\Community\VC")
    • Add Visual C++ Build tools version to BAZEL_VC_FULL_VERSION environment variable (this can be discovered from the directory name in "$BAZEL_VC\Tools\MSVC\<BAZEL_VC_FULL_VERSION>")
  5. Add support for long file names (bazel has a lot of nested directories that can exceed default limits in Windows)
    • Enable Long Paths support with these 2 registry commands:
    reg add "HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Command Processor" /t REG_DWORD /f /v "DisableUNCCheck" /d "1"
reg add "HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\FileSystem" /t REG_DWORD /f /v "LongPathsEnabled" /d "1"
    • Allow Bazel to create short name versions of long file paths: fsutil 8dot3name set 0
    • Set bazel output to C:/tmp instead of nested inside project directory:
      • Create a file selenium/.bazelrc.windows.local
      • Add "startup --output_user_root=C:/tmp" to the file

Alternative Dev Environments

If you want to contribute to the project, but do not want to set up your own local dev environment, there are two alternatives available.

Using GitPod

Rather than creating your own local dev environment, GitPod provides a ready to use environment for you.

Open in Gitpod

Using Dev Container

As an alternative you can build a Dev Container - basically a docker container - suitable for building and testing Selenium using the devcontainer.json in the .devcontainer directory. Supporting IDEs like VS Code or IntelliJ IDEA should point you to how such a container can be created.

Using Docker Image

You can also build a Docker image suitable for building and testing Selenium using the Dockerfile in the dev image directory.

Building

Selenium is built using a common build tool called Bazel, to allow us to easily manage dependency downloads, generate required binaries, build and release packages, and execute tests; all in a fast, efficient manner. For a more detailed discussion, read Simon Stewart's article on Building Selenium

Often we wrap Bazel commands with our custom Rake wrapper. These are run with the ./go command.

The common Bazel commands are:

  • bazel build — evaluates dependencies, compiles source files and generates output files for the specified target. It's used to create executable binaries, libraries, or other artifacts.
  • bazel run — builds the target and then executes it. It's typically used for targets that produce executable binaries.
  • bazel test — builds and runs the target in a context with additional testing functionality
  • bazel query — identifies available targets for the provided path.

Each module that can be built is defined in a BUILD.bazel file. To execute the module you refer to it starting with a //, then include the relative path to the file that defines it, then :, then the name of the target. For example, the target to build the Grid is named executable-grid and it is defined in the 'selenium/java/src/org/openqa/selenium/grid/BAZEL.build' file. So to build the grid you would run: bazel build //java/src/org/openqa/selenium/grid:executable-grid.

The Bazel documentation has a handy guide for various shortcuts and all the ways to build multiple targets, which Selenium makes frequent use of.

To build everything for a given language:

bazel build //<language>/...

To build just the grid there is an alias name to use (the log will show where the output jar is located):

bazel build grid

To make things more simple, building each of the bindings is available with this ./go command

./go <language>:build

Developing

Java

IntelliJ

Most of the team uses Intellij for their day-to-day editing. If you're working in IntelliJ, then we highly recommend installing the Bazel IJ plugin which is documented on its own site.

To use Selenium with the IntelliJ Bazel plugin, import the repository as a Bazel project, and select the project view file from the scripts directory. ij.bazelproject for Mac/Linux and ij-win.bazelproject for Windows.

Linting

We also use Google Java Format for linting, so using the Google Java Formatter Plugin is useful; there are a few steps to get it working, so read their configuration documentation. There is also an auto-formatting script that can be run: ./scripts/format.sh

Local Installation

While Selenium is not built with Maven, you can build and install the Selenium pieces for Maven to use locally by deploying to your local maven repository (~/.m2/repository), using:

./go java:install

Updating Dependencies

Dependencies are defined in the file maven_deps.bzl. To automatically update and pin new dependencies, run:

./go java:update

Python

You can run Python code locally by updating generated files in the python directory using:

./go py:update

To install Selenium locally based on a specific commit, you can use:

./go py:install

Ruby

Instead of using irb, you can create an interactive REPL with all gems loaded using: bazel run //rb:console

If you want to debug code, you can do it via debug gem:

  1. Add binding.break to the code where you want the debugger to start.
  2. Run tests with ruby_debug configuration: bazel test --config ruby_debug <test>.
  3. When debugger starts, run the following in a separate terminal to connect to debugger:
bazel-selenium/external/bundle/bin/rdbg -A

If you want to use RubyMine for development, you can configure it use Bazel artifacts:

  1. Open rb/ as a main project directory.
  2. Run bundle exec rake update as necessary to create up-to-date artifacts. If this does not work, run ./go rb:update from the selenium (parent) directory.
  3. In Settings / Languages & Frameworks / Ruby SDK and Gems add new Interpreter pointing to ../bazel-selenium/external/rules_ruby_dist/dist/bin/ruby.
  4. You should now be able to run and debug any spec. It uses Chrome by default, but you can alter it using environment variables secified in Ruby Testing section below.

Rust

To keep Carbo.Bazel.lock synchronized with Cargo.lock, run:

CARGO_BAZEL_REPIN=true bazel sync --only=crates

Testing

There are a number of bazel configurations specific for testing.

Common Options Examples

Here are examples of arguments we make use of in testing the Selenium code:

  • --pin_browsers - run specific browser versions defined in the build (versions are updated regularly)
  • --headless - run browsers in headless mode (supported be Chrome, Edge and Firefox)
  • --flaky_test_attempts 3 - re-run failed tests up to 3 times
  • --local_test_jobs 1 - control parallelism of tests
  • --cache_test_results=no, -t- - disable caching of test results and re-runs all of them
  • --test_output all - print all output from the tests, not just errors
  • --test_output streamed - run all tests one by one and print its output immediately
  • --test_env FOO=bar - pass extra environment variable to test process
  • --run_under="xvfb-run -a" - prefix to insert before the execution

Filtering

Selenium tests can be filtered by size:

  • small — typically unit tests where no browser is opened
  • large — typically tests that actually drive a browser
  • medium — tests that are more involved than simple unit tests, but not fully driving a browser

These can be filtered using the test_size_filters argument like this:

bazel test //<language>/... --test_size_filters=small

Tests can also be filtered by tag like:

bazel test //<language>/... --test_tag_filters=this,-not-this

Java

Click to see Java Test Commands

To run unit tests:

bazel test //java/... --test_size_filters=small

To run integration tests:

bazel test //java/... --test_size_filters=medium

To run browser tests:

bazel test //java/... --test_size_filters=large --test_tag_filters=<browser>

To run a specific test:

bazel test //java/test/org/openqa/selenium/chrome:ChromeDriverFunctionalTest

JavaScript

Click to see JavaScript Test Commands

To run the tests run:

bazel test //javascript/node/selenium-webdriver:tests

You can use --test_env to pass in the browser name as SELENIUM_BROWSER.

bazel test //javascript/node/selenium-webdriver:tests --test_env=SELENIUM_BROWSER=firefox

Python

Click to see Python Test Commands

Run unit tests with:

bazel test //py:unit

To run tests with a specific browser:

bazel test //py:test-<browsername>

To run all Python tests:

bazel test //py:all

Ruby

Click to see Ruby Test Commands

Test targets:

CommandDescription
bazel test //rb/...Run unit, all integration tests and lint
bazel test //rb:lintRun RuboCop linter
bazel test //rb/spec/...Run unit and integration tests for all browsers
bazel test //rb/spec/... --test_size_filters smallRun unit tests
bazel test //rb/spec/unit/...Run unit tests
bazel test //rb/spec/... --test_size_filters largeRun integration tests for all browsers
bazel test //rb/spec/integration/...Run integration tests for all browsers
bazel test //rb/spec/integration/... --test_tag_filters firefoxRun integration tests for local Firefox only
bazel test //rb/spec/integration/... --test_tag_filters firefox-remoteRun integration tests for remote Firefox only
bazel test //rb/spec/integration/... --test_tag_filters firefox,firefox-remoteRun integration tests for local and remote Firefox

Ruby test targets have the same name as the spec file with _spec.rb removed, so you can run them individually. Integration tests targets also have a browser and remote suffix to control which browser to pick and whether to use Grid.

Test fileTest target
rb/spec/unit/selenium/webdriver/proxy_spec.rb//rb/spec/unit/selenium/webdriver:proxy
rb/spec/integration/selenium/webdriver/driver_spec.rb//rb/spec/integration/selenium/webdriver:driver-chrome
rb/spec/integration/selenium/webdriver/driver_spec.rb//rb/spec/integration/selenium/webdriver:driver-chrome-remote
rb/spec/integration/selenium/webdriver/driver_spec.rb//rb/spec/integration/selenium/webdriver:driver-firefox
rb/spec/integration/selenium/webdriver/driver_spec.rb//rb/spec/integration/selenium/webdriver:driver-firefox-remote

Supported browsers:

  • chrome
  • edge
  • firefox
  • firefox-beta
  • ie
  • safari
  • safari-preview

In addition to the Common Options Examples, here are some additional Ruby specific ones:

  • --test_arg "-eTimeouts" - test only specs which name include "Timeouts"
  • --test_arg "<any other RSpec argument>" - pass any extra RSpec arguments (see bazel run @bundle//bin:rspec -- --help)

Supported environment variables for use with --test_env:

  • WD_SPEC_DRIVER - the driver to test; either the browser name or 'remote' (gets set by Bazel)
  • WD_REMOTE_BROWSER - when WD_SPEC_DRIVER is remote; the name of the browser to test (gets set by Bazel)
  • WD_REMOTE_URL - URL of an already running server to use for remote tests
  • DOWNLOAD_SERVER - when WD_REMOTE_URL not set; whether to download and use most recently released server version for remote tests
  • DEBUG - turns on verbose debugging
  • HEADLESS - for chrome, edge and firefox; runs tests in headless mode
  • DISABLE_BUILD_CHECK - for chrome and edge; whether to ignore driver and browser version mismatches (allows testing Canary builds)
  • CHROME_BINARY - path to test specific Chrome browser
  • CHROMEDRIVER_BINARY - path to test specific ChromeDriver
  • EDGE_BINARY - path to test specific Edge browser
  • MSEDGEDRIVER_BINARY - path to test specific msedgedriver
  • FIREFOX_BINARY - path to test specific Firefox browser
  • GECKODRIVER_BINARY - path to test specific GeckoDriver

To run with a specific version of Ruby you can change the version in rb/.ruby-version or from command line:

echo '<X.Y.Z>' > rb/.ruby-version

.NET

Click to see .NET Test Commands

.NET tests currently only work with pinned browsers, so make sure to include that.

Run all tests with:

bazel test //dotnet/test/common:AllTests --pin_browsers=true

You can run specific tests by specifying the class name:

bazel test //dotnet/test/common:ElementFindingTest --pin_browsers=true

If the module supports multiple browsers:

bazel test //dotnet/test/common:ElementFindingTest-edge --pin_browsers=true

Rust

Click to see Rust Test Commands

Rust tests are run with:

bazel test //rust/...

Linux

Click to see Linux Testing Requirements

By default, Bazel runs these tests in your current X-server UI. If you prefer, you can alternatively run them in a virtual or nested X-server.

  1. Run the X server Xvfb :99 or Xnest :99
  2. Run a window manager, for example, DISPLAY=:99 jwm
  3. Run the tests you are interested in:
bazel test --test_env=DISPLAY=:99 //java/... --test_tag_filters=chrome

An easy way to run tests in a virtual X-server is to use Bazel's --run_under functionality:

bazel test --run_under="xvfb-run -a" //java/...

Documenting

API documentation can be found here:

To update API documentation for a specific language: ./go <language>:docs

To update all documentation: ./go all:docs

Note that JavaScript generation is currently broken.

Releasing

The full process for doing a release can be found in the wiki

Releasing is a combination of building and publishing, which often requires coordination of multiple executions and additional processing. As discussed in the Building section, we use Rake tasks with the ./go command for these things. These ./go commands include the --stamp argument to provide necessary information about the constructed asset.

You can build and release everything with:

./go all:release

To build and release a specific language:

./go <language>:release

If you have access to the Selenium EngFlow repository, you can have the assets built remotely and downloaded locally using:

./go all:release['--config', 'release']

NPM DownloadsLast 30 Days