Selenium Site and Documentation

This is the repository used to build and publish the official Selenium website.

Quick start

We use Hugo and the Docsy theme to build and render the site. You will need the extended Sass/SCSS version of the Hugo binary to work on this site. We recommend to use Hugo 0.125.4

Steps needed to have this working locally and work on it:

• Follow the Install Hugo instructions from Docsy
• Install go
• Clone this repository
• Run cd website_and_docs
• Run hugo server

A full contribution guideline can be seen at contributing

How to get involved?

Please check all the information available at https://selenium.dev/getinvolved/

Do not want to clone the repository to contribute? Use GitPod.

For Selenium Site and Documentation maintainers

How does the site and docs get build?

GitHub actions runs for every commit on each PR and protected branch. The regular CI execution will build the site with Hugo to verify that the commit works. The description of these steps can be seen at the actions configuration file, one for testing a PR, and one for deploying the site

How are the site and docs deployed?

After each CI execution that happens in the trunk branch, the script build-site.sh is executed for deployment. This script checks for the string [deploy site] in the commit message.

If the commit message contains that string, and the commit is in trunk, a GitHub action is triggered to build and deploy the site. The site and docs will be built, and the changes will be committed to the branch publish by the user Selenium-CI.

What is important to take into account is that the source files for the site are in the trunk branch, and the files that get deployed are pushed to the publish branch.

The site is deployed using GitHub pages, and the configuration for this can be seen at the repo settings (if you are a maintainer you should be able to access the link).

The selenium. domain is managed at https://www.gandi.net/en, if you need access to it, reach out to any of the PLC or TLC members, who can help you with that.

If for any reason, you need to setup the domain redirection again, we followed this guide, but any tutorial/guide showing how to redirect a domain to GitHub pages should do.

Maven plugins examples

Maven Plugins:

Here are examples of different useful Maven plugins, showing their typical usage in a pom.xml file:

---

1. Maven Compiler Plugin

Compiles Java source code.

<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-compiler-plugin</artifactId>
  <version>3.11.0</version>
  <configuration>
    <source>17</source>
    <target>17</target>
  </configuration>
</plugin>

==>

4.0.0 com.example maven-compiler-plugin-demo 1.0-SNAPSHOT org.apache.maven.plugins maven-compiler-plugin 3.11.0 17 17

How to use:

Place the above in your pom.xml. Change and to your desired Java version (e.g., 8, 11, 17). Run mvn compile in your project directory. Maven will use the specified Java version for compilation.

---

2. Maven Surefire Plugin

Runs unit tests.

<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-surefire-plugin</artifactId>
  <version>3.1.2</version>
</plugin>

==>

<modelVersion>4.0.0</modelVersion>
<groupId>com.example</groupId>
<artifactId>surefire-demo</artifactId>
<version>1.0-SNAPSHOT</version>
<packaging>jar</packaging>

<build>
    <plugins>
        <!-- Maven Surefire Plugin: runs unit tests -->
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-surefire-plugin</artifactId>
            <version>3.1.2</version>
            <configuration>
                <includes>
                    <include>**/*Test.java</include>
                </includes>
                <!-- You can configure other options here, e.g., system properties, parallel execution, etc. -->
            </configuration>
        </plugin>
    </plugins>
</build>

<dependencies>
    <!-- Example: JUnit for testing -->
    <dependency>
        <groupId>org.junit.jupiter</groupId>
        <artifactId>junit-jupiter</artifactId>
        <version>5.10.2</version>
        <scope>test</scope>
    </dependency>
</dependencies>

How to use:

Add this plugin section to your pom.xml. Place your test classes (e.g., ExampleTest.java) in src/test/java. Run your tests via Maven

mvn test

Surefire will automatically execute your unit tests and provide a summary in the console and reports in target/surefire-reports/. Tip: You can further customize Surefire with options like parallel execution, test includes/excludes, system properties, listeners, etc.

3. Maven Failsafe Plugin

Runs integration tests.

<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-failsafe-plugin</artifactId>
  <version>3.1.2</version>
  <executions>
    <execution>
      <goals>
        <goal>integration-test</goal>
        <goal>verify</goal>
      </goals>
    </execution>
  </executions>
</plugin>

==>

... org.apache.maven.plugins maven-failsafe-plugin 3.1.2 integration-test verify **/IT*.java **/*IT.java ...

How to use:

Place your integration test classes in src/test/java and name them like MyServiceIT.java or ITMyService.java. Run integration tests with

mvn verify

The Failsafe Plugin will execute your integration tests during the integration-test phase and verify results in the verify phase.

Tip:

Use Failsafe for integration tests, and Surefire for unit tests. Failsafe ensures that a failing integration test does not skip the verify phase, allowing proper reporting.

4. Maven Shade Plugin

Creates an uber/fat JAR with all dependencies.

<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-shade-plugin</artifactId>
  <version>3.5.0</version>
  <executions>
    <execution>
      <phase>package</phase>
      <goals>
        <goal>shade</goal>
      </goals>
    </execution>
  </executions>
</plugin>

==>

4.0.0 com.example shade-demo 1.0.0 jar

<dependencies>
    <!-- Example dependency -->
    <dependency>
        <groupId>com.google.guava</groupId>
        <artifactId>guava</artifactId>
        <version>33.0.0-jre</version>
    </dependency>
</dependencies>

<build>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-shade-plugin</artifactId>
            <version>3.5.0</version>
            <executions>
                <execution>
                    <phase>package</phase>
                    <goals>
                        <goal>shade</goal>
                    </goals>
                    <configuration>
                        <transformers>
                            <!-- Adds Main-Class to manifest -->
                            <transformer implementation="org.apache.maven.plugins.shade.resource.ManifestResourceTransformer">
                                <mainClass>com.example.Main</mainClass>
                            </transformer>
                        </transformers>
                    </configuration>
                </execution>
            </executions>
        </plugin>
    </plugins>
</build>

Usage:

Add the plugin section above to your pom.xml. Run mvn package. Your fat/uber JAR will be created in the target/ directory, containing all dependencies. You can run it with: java -jar target/shade-demo-1.0.0.jar Tip: Change com.example.Main in to your actual main class.

---

5. Maven Assembly Plugin

Creates archive files, such as ZIPs or custom JARs.

<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-assembly-plugin</artifactId>
  <version>3.6.0</version>
  <configuration>
    <descriptorRefs>
      <descriptorRef>jar-with-dependencies</descriptorRef>
    </descriptorRefs>
  </configuration>
  <executions>
    <execution>
      <phase>package</phase>
      <goals>
        <goal>single</goal>
      </goals>
    </execution>
  </executions>
</plugin>

==> Maven Assembly Plugin to package your Java project (including all dependencies) into a single JAR file.

org.apache.maven.plugins maven-assembly-plugin 3.6.0 com.example.MainClass jar-with-dependencies make-assembly package single

Step 2: Build the Project

mvn clean package

After the build, you’ll find a jar file named like yourproject-1.0-SNAPSHOT-jar-with-dependencies.jar in the target directory. This jar includes your code and all dependencies—ready to run with java -jar.

Tip: You can also customize the assembly with a descriptor file for ZIP, TAR, or other formats. For more details, see the official documentation.

---

6. Maven Javadoc Plugin

Generates Javadoc documentation.

<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-javadoc-plugin</artifactId>
  <version>3.6.3</version>
</plugin>

==> Maven Javadoc Plugin in your pom.xml to generate Javadoc documentation for your Java project:

org.apache.maven.plugins maven-javadoc-plugin 3.6.3 attach-javadocs jar UTF-8 17 public

How to use:

mvn javadoc:javadoc

This generates Javadoc HTML files in your target/site/apidocs directory.

To create a Javadoc JAR for distribution, run:

mvn javadoc:jar

This produces a JAR file with your documentation in target/.

Tip: You can further customize the plugin (for links, suppressing warnings, etc.) using the section.

7. Maven Clean Plugin

Removes target directory before building.

<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-clean-plugin</artifactId>
  <version>3.3.2</version>
</plugin>

==> Maven Clean Plugin is used to remove the target directory and all the files generated by the previous build. This is usually run with the mvn clean command before a build.

org.apache.maven.plugins maven-clean-plugin 3.3.2 ${project.build.directory} *.log

This configuration:

Uses version 3.3.2 of the plugin. Cleans the target directory (default). Additionally, removes any .log files in the build directory.

How to Run

From the command line, execute:

mvn clean

This will delete the target directory and any additional files specified in the plugin configuration.

Tip: You usually don’t need custom configuration unless you want to clean up more than the default build output. You can also run mvn clean install to clean and then build your project.

---

8. Maven Dependency Plugin

Manages and analyzes dependencies.

<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-dependency-plugin</artifactId>
  <version>3.6.1</version>
</plugin>

==> Maven Dependency Plugin provides goals for analyzing, resolving, copying, and managing dependencies. Here’s a basic example of how to use it in your pom.xml, and some common goals you can run.

org.apache.maven.plugins maven-dependency-plugin 3.6.1 copy-dependencies prepare-package copy-dependencies ${project.build.directory}/libs

This example will copy all runtime dependencies to the target/libs folder during the build.

Common Usage from Command Line: Analyze dependencies: mvn dependency:analyze

List dependencies: mvn dependency:list

Copy dependencies: mvn dependency:copy-dependencies

Get dependency tree: mvn dependency:tree

Unpack a dependency: mvn dependency:unpack -Dartifact=groupId:artifactId:version -DoutputDirectory=target/unpacked

Tip: You can use this plugin to troubleshoot dependency issues, copy JARs for packaging, or analyze unused dependencies in your project.

---

9. Maven Site Plugin

Generates a project site.

<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-site-plugin</artifactId>
  <version>4.0.0-M13</version>
</plugin>

==>

org.apache.maven.plugins maven-site-plugin 4.0.0-M13 site-output

How to use:

Add the plugin configuration above to your pom.xml. Run the following Maven command in your project directory:

mvn site

This will generate a project documentation website (including reports, Javadoc, dependency info, and more) inside the target/site or your configured output directory.

Tip: You can further customize the site content and appearance using section, site descriptors, or adding custom reports. For example, to include Javadoc and Surefire reports:

org.apache.maven.plugins maven-javadoc-plugin org.apache.maven.plugins maven-surefire-report-plugin

---

10. Maven Resources Plugin

Copies and filters resources.

<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-resources-plugin</artifactId>
  <version>3.3.1</version>
</plugin>

==> give an example how to use Maven Resources Plugin

4.0.0 com.example resources-plugin-demo 1.0-SNAPSHOT org.apache.maven.plugins maven-resources-plugin 3.3.1 copy-resources process-resources copy-resources ${project.build.directory}/extra-resources src/main/resources-extra **/*.txt **/*.properties true

How this works:

This example configures the Maven Resources Plugin to copy all .txt and .properties files from src/main/resources-extra to target/extra-resources. The true option allows you to use Maven property placeholders (e.g., ${project.version}) in your resource files. Runs in the process-resources phase.

Basic usage:

By default, Maven copies files from src/main/resources to target/classes without special configuration. The above example shows how to copy additional resources or customize behavior.

mvn resources:copy-resources

---

Tip:
Most plugins are used in the <build><plugins></plugins></build> section in your pom.xml.
You can customize goals, executions, and configurations as needed for your project.