Development Setup and Contributing

Relevant source files

• .ffmpeg/Dockerfile
• .github/workflows/k8s-scaling-test.yml
• .github/workflows/release-chrome-versions.yml
• .github/workflows/release-edge-versions.yml
• .github/workflows/release-firefox-versions.yml
• Base/Dockerfile
• charts/selenium-grid/multiple-nodes-platform-version.yaml
• tests/SeleniumTests/__init__.py
• tests/SmokeTests/__init__.py
• tests/bootstrap.sh
• tests/build-backward-compatible/browser-matrix.yml
• tests/build-backward-compatible/firefox-matrix.yml
• tests/build-backward-compatible/selenium-matrix.yml
• tests/charts/make/chart_setup_env.sh
• tests/test.py

This page provides guidance for contributors who want to set up a local development environment, build Docker images, run tests, and submit contributions to the docker-selenium project. It covers environment setup, build processes, local testing procedures, and contribution workflows. For information about the testing framework architecture and test suites, see Testing Framework and Test Suites.

---

Prerequisites

Before setting up the development environment, ensure your system meets these requirements:

Requirement	Minimum Version	Recommended	Purpose
Operating System	Ubuntu 20.04+	Ubuntu 22.04/24.04	Development and CI environment
RAM	8 GB	16 GB+	Building multi-architecture images
Disk Space	50 GB	100 GB+	Docker images, build cache, test artifacts
CPU Architecture	AMD64 or ARM64	AMD64	Multi-arch support
Internet Connection	Required	High-speed	Downloading dependencies

Sources: tests/charts/make/chart_setup_env.sh1-219

---

Development Environment Setup

The project provides an automated setup script that installs all required dependencies. The setup process configures Docker with multi-architecture support, Kubernetes tools, and testing utilities.

Setup Script Overview

Diagram: Development Environment Setup Flow

Sources: tests/charts/make/chart_setup_env.sh1-219

Running the Setup Script

The setup script is located at tests/charts/make/chart_setup_env.sh and can be invoked via the Makefile:

The script installs the following components:

Docker Components

• Docker CE: Container runtime (configurable version via DOCKER_VERSION)
• containerd.io: Container runtime daemon
• docker-buildx-plugin: Multi-architecture build support
• docker-compose-plugin: Compose V2 functionality
• docker-sbom-plugin: Software Bill of Materials generation

Sources: tests/charts/make/chart_setup_env.sh48-91

Multi-Architecture Support

Cross-compilation tools and QEMU emulation for building ARM64 images on AMD64 hosts:

Sources: tests/charts/make/chart_setup_env.sh60-77

Kubernetes Tools

The script supports two cluster types via the CLUSTER environment variable:

Kind (Kubernetes in Docker)

• Lightweight Kubernetes cluster running in Docker containers
• Suitable for quick local testing
• Faster startup times

Minikube (Default)

• Full-featured local Kubernetes cluster
• Supports CRI-dockerd for Docker runtime
• Requires additional dependencies (conntrack, CRI-dockerd, CNI plugins)

Sources: tests/charts/make/chart_setup_env.sh93-161

Additional Tools

Tool	Purpose	Installation Source
kubectl	Kubernetes CLI	Official Kubernetes releases
Helm	Kubernetes package manager	Helm GitHub releases
chart-testing (ct)	Helm chart linting and testing	helm/chart-testing
helm-docs	Generate Helm documentation	norwoodj/helm-docs
envsubst	Template substitution	a8m/envsubst
Node.js/npm	JavaScript tooling (via nvm)	nvm-sh/nvm

Sources: tests/charts/make/chart_setup_env.sh163-218

Docker Configuration for Containerd Image Store

The project uses Docker's containerd image store feature for improved performance and storage efficiency:

This configuration is automatically applied by make setup_dev_env and provides:

• Faster image builds and pulls
• Reduced disk space usage
• Native multi-platform support
• Better integration with Kubernetes

Sources: .github/workflows/release-chrome-versions.yml75-81

---

Building Docker Images Locally

The project uses a Makefile-based build system that orchestrates Docker image builds with multi-architecture support.

Build System Architecture

Diagram: Image Build Dependency Chain

Sources: Base/Dockerfile1-235 tests/test.py170-221

Basic Build Commands

Multi-Architecture Builds

The build system supports building images for multiple platforms simultaneously using Docker Buildx:

Build Arguments Mapping:

Environment Variable	Build Arg	Default	Purpose
VERSION	VERSION	(from file)	Image version tag
BASE_VERSION	BASE_VERSION	(from upstream)	Selenium Grid version
BASE_RELEASE	RELEASE	selenium-${VERSION}	Selenium JAR release name
NAMESPACE	AUTHORS	selenium	Docker registry namespace
BUILD_DATE	BUILD_DATE	Current date	Build timestamp

Sources: tests/test.py109-114

Building Browser-Specific Versions

The project maintains browser version matrices for backward compatibility testing. To build a specific browser version:

The bootstrap.sh script:

1. Reads browser version from tests/build-backward-compatible/browser-matrix.yml
2. Sets appropriate environment variables (CHROME_VERSION, FIREFOX_VERSION, EDGE_VERSION)
3. Builds node and standalone images with version-specific tags
4. Optionally pushes images to registry

Sources: .github/workflows/release-chrome-versions.yml115-126 tests/build-backward-compatible/browser-matrix.yml1-207

Build Process Internals

Diagram: Docker Image Build Process Flow

The build process in tests/test.py170-221 performs these steps:

1. Platform Detection: Determines the current architecture (AMD64 or ARM64)
2. Image Check: Verifies if SKIP_BUILD is set to reuse existing images
3. Build Arguments: Assembles build arguments from environment variables
4. Docker Build: Invokes docker.images.build() with appropriate parameters
5. Dependency Resolution: Automatically builds base images if needed (for standalone images)

Sources: tests/test.py117-238

---

Running Tests Locally

The project has two test levels: Docker-level tests that validate individual images, and Kubernetes-level tests that verify Helm chart deployments.

Test Execution Framework

Diagram: Test Execution Pipeline

Sources: tests/bootstrap.sh1-41 tests/test.py1-318

Docker-Level Tests

Docker tests validate individual images by launching containers and running Selenium WebDriver tests.

Running Docker Tests

Test Script Bootstrap Process

The tests/bootstrap.sh1-41 script performs these steps:

1. Virtual Environment: Creates or activates Python virtual environment
2. Selenium Bindings: Installs appropriate version of Selenium Python bindings
   • For snapshot versions: Installs from test.pypi.org
   • For release versions: Installs from pypi.org using BINDING_VERSION
3. Dependencies: Installs requirements from tests/requirements.txt
4. Test Execution: Runs either test.py or specific unittest classes

Sources: tests/bootstrap.sh1-41

Test Orchestration Flow

Diagram: test.py Orchestration Logic

The tests/test.py1-318 orchestrator:

1. Container Launch: Creates Hub and Node containers (or Standalone)
   • Standalone: Single container on port 4444
   • Hub/Node: Hub on 4442/4443/4444, Node on 5555/7900
2. Smoke Tests: Verifies Grid /status endpoint is ready
3. Selenium Tests: Runs browser automation tests
4. Cleanup: Removes all launched containers

Container Launch Configuration:

Sources: tests/test.py170-221 tests/test.py241-318

Test Suites

The test framework includes two main test suite types defined in tests/SeleniumTests/__init__.py1-400:

SeleniumGenericTests Base Class:

• test_title(): Verifies page title loading
• test_with_frames(): Tests frame switching
• test_select_from_a_dropdown(): Tests dropdown interaction
• test_visit_basic_auth_secured_page(): Tests HTTP basic auth
• test_play_video(): Tests video playback
• test_download_file(): Tests file downloads (with managed downloads)

Browser-Specific Test Classes:

• ChromeTests: Extends SeleniumGenericTests with Chrome-specific options
• FirefoxTests: Extends with Firefox profile configuration, language tests
• EdgeTests: Extends with Edge-specific options

Autoscaling Test Classes:

• DeploymentAutoscalingTests: Tests KEDA autoscaling with Deployments
• JobAutoscalingTests: Tests KEDA autoscaling with Jobs

Sources: tests/SeleniumTests/__init__.py65-400

Kubernetes/Helm Tests

Helm chart tests validate Kubernetes deployments across multiple dimensions: K8s versions, autoscaling strategies, and configuration scenarios.

Running Helm Chart Tests

Test Matrix Configuration

The CI system tests against multiple combinations:

Dimension	Values	Source
K8s Versions	v1.28.15, v1.29.15, v1.30.14, v1.31.12, v1.32.9, v1.34.1	.github/workflows/k8s-scaling-test.yml
Helm Versions	v3.14.3 - v3.19.0	.github/workflows/k8s-scaling-test.yml
Docker Versions	27.5.1, 28.4.0	.github/workflows/k8s-scaling-test.yml
Python Versions	3.9, 3.10, 3.11, 3.12, 3.13	.github/workflows/k8s-scaling-test.yml
Test Strategies	deployment_count, job_count, chaos, node_max_sessions	.github/workflows/k8s-scaling-test.yml

Sources: .github/workflows/k8s-scaling-test.yml66-116

Helm Chart Test Process

Diagram: Helm Chart Test Pipeline

Sources: .github/workflows/k8s-scaling-test.yml123-213

Test Configuration via Environment Variables

Tests can be configured using environment variables:

Sources: tests/SeleniumTests/__init__.py17-41

---

Contributing Workflow

Repository Setup

Development Cycle

Diagram: Contribution Workflow

Making Changes

1. Create a Feature Branch

2. Make and Test Changes

3. Verify Multi-Architecture Support (if applicable)

4. Commit Changes

Commit Message Guidelines:

• First line: Brief summary (50 chars or less)
• Blank line
• Detailed description of changes
• Reference relevant issue numbers

5. Push and Create Pull Request

CI/CD Validation

When you create a pull request, GitHub Actions automatically runs:

1. Build Test Workflow: Builds all images and runs Docker tests
2. Helm Chart Test Workflow: Tests Kubernetes deployments
3. Linting: Validates Dockerfile and shell script syntax

The workflows defined in .github/workflows/build-test.yml execute:

• Multi-architecture image builds
• Smoke tests and Selenium tests
• Helm chart validation
• Browser version matrix tests

Sources: .github/workflows/release-chrome-versions.yml1-169

Code Review Process

Pull requests undergo review by project maintainers who check:

• Code Quality: Adherence to coding standards
• Test Coverage: All changes have corresponding tests
• Documentation: README and wiki updates if needed
• Backward Compatibility: No breaking changes without discussion
• CI Status: All automated checks pass

---

Common Development Tasks

Building a Specific Browser Version

To build and test a legacy browser version for backward compatibility:

Browser Version Matrix Files:

• tests/build-backward-compatible/browser-matrix.yml: Comprehensive browser version catalog
• tests/build-backward-compatible/selenium-matrix.yml: Selenium Grid version mappings
• tests/build-backward-compatible/firefox-matrix.yml: Firefox-specific version details

Sources: .github/workflows/release-chrome-versions.yml115-147 tests/build-backward-compatible/browser-matrix.yml1-207

Testing Backward Compatibility

When testing compatibility with older Selenium Grid versions:

Sources: tests/SeleniumTests/__init__.py39-45 tests/build-backward-compatible/selenium-matrix.yml1-206

Debugging Test Failures

When tests fail, follow this debugging approach:

Test Environment Variables:

Variable	Purpose	Default
SKIP_BUILD	Skip rebuilding images	false
PLATFORMS	Target architectures	linux/amd64
FILESYSTEM_READ_ONLY	Test read-only filesystem	false
USE_RANDOM_USER_ID	Test non-root user	false
TEST_DELAY_AFTER_TEST	Delay between tests (seconds)	0

Sources: tests/test.py43-54 tests/SeleniumTests/__init__.py17-41

Adding a New Browser Node

To add support for a new browser (e.g., Chromium variant):

1. Create Dockerfile in new directory (e.g., NodeChromiumCustom/)
2. Base on existing node image:

3. Update Makefile with new target:

4. Add test configuration in tests/test.py:

5. Create test case:

Sources: Base/Dockerfile1-235 tests/test.py61-107

Contributing Documentation

When contributing documentation changes:

Documentation sources:

• Chart README: Auto-generated from README.md.gotmpl template
• Wiki pages: Maintained in separate repository
• Code comments: Inline documentation in source files

Sources: tests/charts/make/chart_setup_env.sh197-200

---

Development Best Practices

Code Style and Standards

• Shell Scripts: Use ShellCheck for linting
• Python: Follow PEP 8 style guidelines
• Dockerfiles: Use multi-stage builds, minimize layers
• YAML: Consistent indentation (2 spaces)

Testing Guidelines

• Test changes locally before pushing
• Add tests for new features
• Ensure backward compatibility
• Test on both AMD64 and ARM64 if possible
• Run full test suite for critical changes

Security Considerations

• Never commit credentials or secrets
• Use build-time secrets for sensitive data (Base/Dockerfile89)
• Keep base images and dependencies updated
• Review security advisories for dependencies

Sources: Base/Dockerfile89-115

Performance Optimization

• Use .dockerignore to exclude unnecessary files
• Leverage Docker layer caching
• Use containerd image store for faster builds
• Pin dependency versions for reproducibility

---

Getting Help

• Issues: Search existing issues on GitHub before creating new ones
• Discussions: Use GitHub Discussions for questions
• Slack: Join SeleniumHQ Slack for community support
• Documentation: Refer to README files in component directories

Sources: Repository README and community guidelines