Implementation:SeleniumHQ Selenium Language AGENTS Conventions

Knowledge Sources	Selenium
Domains	Code_Quality, Developer_Experience, Standards
Last Updated	2026-02-11 00:00 GMT

Overview

Pattern documentation for language-specific coding conventions defined in AGENTS.md files across the Selenium monorepo.

Description

Each language binding directory contains an AGENTS.md file with conventions for that language. These are Pattern Docs that define interfaces and expectations for contributors rather than documenting specific APIs. Key conventions include logging framework usage, deprecation marking, documentation style, source layout, type safety, and testing approach. Each AGENTS.md also references a language-specific TESTING.md for test execution details.

Usage

Read the relevant AGENTS.md before contributing to any language binding. Follow the conventions for all new code. When changing user-visible behavior, compare with at least one other binding using rg <term> java/ py/ rb/ dotnet/ javascript/selenium-webdriver/ for cross-binding consistency.

Code Reference

Source Location

• Repository: Selenium
• File: java/AGENTS.md
• File: py/AGENTS.md
• File: rb/AGENTS.md
• File: rust/AGENTS.md
• File: dotnet/AGENTS.md

Interface Specification

Java (java/AGENTS.md)

// Source layout: java/src/, java/test/
// Grid: java/src/org/openqa/selenium/grid/

// Logging
import java.util.logging.Logger;
private static final Logger LOG = Logger.getLogger(MyClass.class.getName());
LOG.warning("actionable: something needs attention");
LOG.info("useful: server started on port 4444");
LOG.fine("diagnostic: request details for debugging");

// Deprecation
@Deprecated(forRemoval = true)
public void legacyMethod() { }

// Documentation: Javadoc for public APIs
/**
 * Brief description.
 *
 * @param name description
 * @return description
 * @throws ExceptionType when condition
 */

Python (py/AGENTS.md)

# Source layout: py/selenium/, py/selenium/webdriver/remote/
# Type hints required on new code

# Logging
import logging
logger = logging.getLogger(__name__)
logger.warning("actionable: something needs attention")
logger.info("useful: driver started successfully")
logger.debug("diagnostic: request payload for debugging")

# Deprecation
import warnings
warnings.warn(
    "old_method is deprecated, use new_method instead",
    DeprecationWarning,
    stacklevel=2
)

# Documentation: Google-style docstrings
def method(param: str) -> bool:
    """Brief description.

    Args:
        param: Description of param.

    Returns:
        Description of return value.

    Raises:
        ValueError: When condition.
    """

Ruby (rb/AGENTS.md)

# Source layout: rb/lib/selenium/webdriver, rb/spec/unit/, rb/spec/integration/
# Type signatures: rb/sig/ (.rbs files, update when changing public API)

# Logging
WebDriver.logger.warn("actionable: something needs attention", id: :warning_id)
WebDriver.logger.info("useful: driver started successfully")
WebDriver.logger.debug("diagnostic: request details for debugging")

# Deprecation
WebDriver.logger.deprecate(
  'OldClass#old_method',
  'NewClass#new_method',
  id: :old_method
)

# Internal APIs: mark with @api private
# @api private
def internal_method
end

# Documentation: YARD for public APIs
# Brief description.
#
# @param name [Type] description
# @return [Type] description
# @raise [ErrorClass] when condition

Rust (rust/AGENTS.md)

// Source layout: rust/src/, rust/tests/

// Logging
use log::{warn, info, debug};
warn!("actionable: something needs attention");
info!("useful: browser resolved successfully");
debug!("diagnostic: request details for debugging");

// Deprecation
#[deprecated(since = "0.1.0", note = "Use new_function instead")]
pub fn old_function() { }

// Documentation: doc comments
/// Brief description.
///
/// # Arguments
/// * `name` - description
///
/// # Returns
/// Description of return value.
///
/// # Errors
/// Returns `ErrorType` when condition.

.NET (dotnet/AGENTS.md)

// Source layout: dotnet/src/webdriver/, dotnet/src/support/, dotnet/test/common/
// Codebase is migrating to async

// Logging
using OpenQA.Selenium.Internal.Logging;
private static readonly ILogger _logger = Log.GetLogger<MyClass>();
_logger.Warn("actionable: something needs attention");
_logger.Info("useful: driver started successfully");
_logger.Debug("diagnostic: request details for debugging");

// Deprecation
[Obsolete("Use NewMethod instead")]
public void OldMethod() { }

// Documentation: XML doc comments
/// <summary>
/// Brief description.
/// </summary>
/// <param name="name">Description.</param>
/// <returns>Description.</returns>
/// <exception cref="ExceptionType">When condition.</exception>

Import

N/A - Pattern documentation, not importable code

I/O Contract

Inputs

Name	Type	Required	Description
Language	String	Yes	java, py, rb, rust, dotnet
AGENTS.md	File	Yes	Language-specific convention file in binding directory

Outputs

Name	Type	Description
Compliant code	Source files	Code following language-specific conventions for logging, deprecation, docs, and style

Usage Examples

Source Layout by Language

Language	Source Directory	Test Directory	Convention File
Java	java/src/	java/test/	java/AGENTS.md
Python	py/selenium/	(in py:unit target)	py/AGENTS.md
Ruby	rb/lib/selenium/webdriver	rb/spec/unit/, rb/spec/integration/	rb/AGENTS.md
Rust	rust/src/	rust/tests/	rust/AGENTS.md
.NET	dotnet/src/webdriver/	dotnet/test/common/	dotnet/AGENTS.md

License Header (Required on Every File)

Licensed to the Software Freedom Conservancy (SFC) under one
or more contributor license agreements.  See the NOTICE file
distributed with this work for additional information
regarding copyright ownership.  The SFC licenses this file
to you under the Apache License, Version 2.0 (the
"License"); you may not use this file except in compliance
with the License.  You may obtain a copy of the License at

  http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing,
software distributed under the License is distributed on an
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
KIND, either express or implied.  See the License for the
specific language governing permissions and limitations
under the License.

Related Pages

Implements Principle

• Principle:SeleniumHQ_Selenium_Coding_Convention_Compliance

Uses Heuristic

• Heuristic:SeleniumHQ_Selenium_Cross_Binding_Consistency_Check