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)

• Open Powershell as an Administrator
• Execute: Set-ExecutionPolicy Bypass -Scope Process -Force to allow running the script in the process
• Navigate to the directory you want to clone Selenium in, or the parent directory of an already cloned Selenium repo
• 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: %%CODEBLOCK0%% 2. Enable Developer Mode: %%CODEBLOCK1%% 3. Install [MSYS2](https://www.msys2.org/), 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 BAZELSH environment variable (e.g., "C:\tools\msys64\usr\bin\bash.exe") 4. Install the latest version of [Visual Studio Community](https://visualstudio.microsoft.com/vs/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 BAZELVC environment variable (e.g. "C:\Program Files\Microsoft Visual Studio\2022\Community\VC") * Add Visual C++ Build tools version to BAZELVCFULLVERSION environment variable (this can be discovered from the directory name in "$BAZELVC\Tools\MSVC\VCFULLVERSION>") 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: %%CODEBLOCK2%% * 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 </details> ### 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](https://gitpod.io/button/open-in-gitpod.svg)](https://gitpod.io/#https://github.com/SeleniumHQ/selenium) #### Using Dev Container As an alternative you can build a [Dev Container](https://containers.dev/) - basically a docker container - suitable for building and testing Selenium using the devcontainer.json in the [.devcontainer](.devcontainer/devcontainer.json) 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](scripts/dev-image/Dockerfile) directory. ## Building Selenium is built using a common build tool called [Bazel](https://bazel.build/), 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](https://www.selenium.dev/blog/2023/building-selenium/) Often we wrap Bazel commands with our custom [Rake](http://rake.rubyforge.org/) 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](https://bazel.build/run/build#specifying-build-targets) for various shortcuts and all the ways to build multiple targets, which Selenium makes frequent use of. To build everything for a given language: %%CODEBLOCK3%% To build just the grid there is an alias name to use (the log will show where the output jar is located): %%CODEBLOCK4%% To make things more simple, building each of the bindings is available with this ./go command: %%CODEBLOCK5%% ## 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](https://plugins.jetbrains.com/plugin/8609-bazel) which is documented on [its own site](https://plugins.jetbrains.com/plugin/8609-bazel). To use Selenium with the IntelliJ Bazel plugin, import the repository as a Bazel project, and select the project view file from the [scripts](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](https://github.com/google/google-java-format/blob/master/README.md#intellij-jre-config). 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: %%CODEBLOCK6%% #### Updating Dependencies Dependencies are defined in the file [MODULE.bazel](https://github.com/SeleniumHQ/selenium/blob/trunk/MODULE.bazel). To update a dependency, modify the version in the MODULE.bazel file and run: %%CODEBLOCK7%% To automatically update and pin new dependencies, run: %%CODEBLOCK8%% ### Python #### Linting and Formatting We follow the [PEP8 Style Guide for Python Code](https://peps.python.org/pep-0008) (except we use a 120 character line length). This is checked and enforced with [ruff](https://docs.astral.sh/ruff/), a linting/formatting tool. There is also an auto-formatting script that can be run: ./scripts/format.sh #### Local Installation To run Python code locally without building/installing the package, you must first install the dependencies: %%CODEBLOCK9%% Then, build the generated files and copy them into your local source tree: %%CODEBLOCK10%% After that, you can import the selenium package directly from source from the py directory. Instead of running from source, you can build and install the selenium package (wheel) locally: %%CODEBLOCK11%% This will attempt to install into the global Python site-packages directory, which might not be writable. To avoid this, you should create and activate a [virtual environment](https://packaging.python.org/en/latest/tutorials/installing-packages/#creating-virtual-environments) before installing. ### 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](https://github.com/ruby/debug) gem: 1. Add binding.break to the code where you want the debugger to start. 2. Run tests with rubydebug configuration: bazel test --config rubydebug . 3. When debugger starts, run the following in a separate terminal to connect to debugger: %%CODEBLOCK12%% If you want to use [RubyMine](https://www.jetbrains.com/ruby/) for development, you can configure it use Bazel artifacts: 1. Open rb/ as a main project directory. 2. From the selenium (parent) directory, run ./go rb:localdev to create up-to-date artifacts. 3. In <kbd>Settings / Languages & Frameworks / Ruby SDK and Gems</kbd> add new <kbd>Interpreter</kbd> pointing to ../bazel-selenium/external/rulesruby++ruby+ruby/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 specified in [Ruby Testing](#ruby-2) section below. ### Rust To keep Cargo.Bazel.lock synchronized with Cargo.lock, run: %%CODEBLOCK13%% ## 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: * --pinbrowsers=false - use Selenium Manager to locate browsers/drivers * --headless - run browsers in headless mode (supported be Chrome, Edge and Firefox) * --flakytestattempts 3 - re-run failed tests up to 3 times * --localtestjobs 1 - control parallelism of tests * --cachetestresults=no, -t- - disable caching of test results and re-runs all of them * --testoutput all - print all output from the tests, not just errors * --testoutput streamed - run all tests one by one and print its output immediately * --testenv FOO=bar - pass extra environment variable to test process * --rununder="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 testsizefilters argument like this: %%CODEBLOCK14%% Tests can also be filtered by tag like: %%CODEBLOCK15%% If there are multiple --testtagfilters, only the last one is considered, so be careful if also using an inherited config ### Java <details> <summary>Click to see Java Test Commands</summary> To run unit tests: %%CODEBLOCK16%% To run integration tests: %%CODEBLOCK17%% To run browser tests: %%CODEBLOCK18%% To run a specific test: %%CODEBLOCK19%% </details> ### JavaScript <details> <summary>Click to see JavaScript Test Commands</summary> To run the tests run: %%CODEBLOCK20%% You can use --testenv to pass in the browser name as SELENIUMBROWSER. %%CODEBLOCK21%% </details> ### Python <details> <summary>Click to see Python Test Commands</summary> Run unit tests with: %%CODEBLOCK22%% To run all tests with a specific browser: %%CODEBLOCK23%% To run common tests with a specific browser (include BiDi tests): %%CODEBLOCK24%% To run all Python tests: %%CODEBLOCK25%% To run tests headless: %%CODEBLOCK26%% </details> ### Ruby <details> <summary>Click to see Ruby Test Commands</summary> Test targets: | Command | Description | | -------------------------------------------------------------------------------- | -------------------------------------------------- | | bazel test //rb/... | Run unit, all integration tests and lint | | bazel test //rb:lint | Run RuboCop linter | | bazel test //rb/spec/... | Run unit and integration tests for all browsers | | bazel test //rb/spec/... --testsizefilters small | Run unit tests | | bazel test //rb/spec/unit/... | Run unit tests | | bazel test //rb/spec/... --testsizefilters large | Run integration tests for all browsers | | bazel test //rb/spec/integration/... | Run integration tests for all browsers | | bazel test //rb/spec/integration/... --testtagfilters firefox | Run integration tests for local Firefox only | | bazel test //rb/spec/integration/... --testtagfilters firefox-remote | Run integration tests for remote Firefox only | | bazel test //rb/spec/integration/... --testtagfilters firefox,firefox-remote | Run 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 file | Test target | | ------------------------------------------------------- | ---------------------------------------------------------------- | | rb/spec/unit/selenium/webdriver/proxyspec.rb | //rb/spec/unit/selenium/webdriver:proxy | | rb/spec/integration/selenium/webdriver/driverspec.rb | //rb/spec/integration/selenium/webdriver:driver-chrome | | rb/spec/integration/selenium/webdriver/driverspec.rb | //rb/spec/integration/selenium/webdriver:driver-chrome-remote | | rb/spec/integration/selenium/webdriver/driverspec.rb | //rb/spec/integration/selenium/webdriver:driver-firefox | | rb/spec/integration/selenium/webdriver/driverspec.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](#common-options-examples), here are some additional Ruby specific ones: * --testarg "-eTimeouts" - test only specs which name include "Timeouts" * --testarg "" - pass any extra RSpec arguments (see bazel run @bundle//bin:rspec -- --help) Supported environment variables for use with --testenv: - WDSPECDRIVER - the driver to test; either the browser name or 'remote' (gets set by Bazel) - WDREMOTEBROWSER - when WDSPECDRIVER is remote; the name of the browser to test (gets set by Bazel) - WDREMOTEURL - URL of an already running server to use for remote tests - DOWNLOADSERVER - when WDREMOTEURL 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 - DISABLEBUILDCHECK - for chrome and edge; whether to ignore driver and browser version mismatches (allows testing Canary builds) - CHROMEBINARY - path to test specific Chrome browser - CHROMEDRIVERBINARY - path to test specific ChromeDriver - EDGEBINARY - path to test specific Edge browser - MSEDGEDRIVERBINARY - path to test specific msedgedriver - FIREFOXBINARY - path to test specific Firefox browser - GECKODRIVERBINARY - 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: %%CODEBLOCK27%% </details> ### .NET <details> <summary>Click to see .NET Test Commands</summary> .NET tests currently only work with pinned browsers, so make sure to include that. Run all tests with: %%CODEBLOCK28%% You can run specific tests by specifying the class name: %%CODEBLOCK29%% If the module supports multiple browsers: %%CODEBLOCK30%% </details> ### Rust <details> <summary>Click to see Rust Test Commands</summary> Rust tests are run with: %%CODEBLOCK31%% </details> ### Linux <details> <summary>Click to see Linux Testing Requirements</summary> 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: %%CODEBLOCK32%% An easy way to run tests in a virtual X-server is to use Bazel's --run_under functionality: %%CODEBLOCK33%% </details> ## Documenting API documentation can be found here: * [C#](https://seleniumhq.github.io/selenium/docs/api/dotnet/) * [JavaScript](https://seleniumhq.github.io/selenium/docs/api/javascript/) * [Java](https://seleniumhq.github.io/selenium/docs/api/java/index.html) * [Python](https://seleniumhq.github.io/selenium/docs/api/py/) * [Ruby](https://seleniumhq.github.io/selenium/docs/api/rb/) To update API documentation for a specific language: ./go :docs To update all documentation: ./go all:docs ## Releasing The full process for doing a release can be found in [the wiki](https://github.com/SeleniumHQ/selenium/wiki/Releasing-Selenium) Releasing is a combination of building and publishing, which often requires coordination of multiple executions and additional processing. As discussed in the [Building](#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.

./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']