Restore translated documentation pages removed by the Docsy upgrade

.github/workflows/java-examples.yml

@@ -62,62 +62,50 @@ jobs:
       run: keytool -import -noprompt -trustcacerts -alias SeleniumHQ -file examples/java/src/test/resources/tls.crt -keystore ${{ steps.java.outputs.path }}/lib/security/cacerts -storepass changeit
     - name: Run Tests Stable (in Maven)
       if: matrix.release == 'stable'
-      uses: nick-invision/retry@v4.0.0
-      with:
-        timeout_minutes: 40
-        max_attempts: 3
-        command: |
-          cd examples/java
-          mvn -B test -D"jdk.internal.httpclient.disableHostnameVerification=true"
+      timeout-minutes: 40
+      run: |
+        cd examples/java
+        mvn -B test -D"jdk.internal.httpclient.disableHostnameVerification=true"
     - name: Run Tests Stable (in Gradle)
       if: matrix.release == 'stable'
-      uses: nick-invision/retry@v4.0.0
-      with:
-        timeout_minutes: 40
-        max_attempts: 3
-        command: |
-          cd examples/java
-          ./gradlew test --tests 'dev.selenium.*UsingSeleniumTest'
+      timeout-minutes: 40
+      run: |
+        cd examples/java
+        ./gradlew test --tests 'dev.selenium.*UsingSeleniumTest'
     - name: Run Tests Nightly Linux/macOS
       if: matrix.release == 'nightly' && matrix.os != 'windows'
-      uses: nick-invision/retry@v4.0.0
-      with:
-        timeout_minutes: 40
-        max_attempts: 3
-        command: |
-          # Get current selenium.version from Maven
-          current_version=$(mvn -f examples/java/pom.xml help:evaluate -Dexpression=selenium.version -q -DforceStdout)
-          echo "Current selenium.version: $current_version"
-          # If version is in the form X.Y.Z, bump minor and set to SNAPSHOT
-          if [[ $current_version =~ ^([0-9]+)\.([0-9]+)\.([0-9]+)$ ]]; then
-            major="${BASH_REMATCH[1]}"
-            minor="${BASH_REMATCH[2]}"
-            next_minor=$((minor + 1))
-            new_version="$major.$next_minor.0-SNAPSHOT"
-            echo "Using selenium.version $new_version for tests"
-            cd examples/java
-            mvn -B -U test -D"jdk.internal.httpclient.disableHostnameVerification=true" -Dselenium.version=$new_version
-          fi
+      timeout-minutes: 40
+      run: |
+        # Get current selenium.version from Maven
+        current_version=$(mvn -f examples/java/pom.xml help:evaluate -Dexpression=selenium.version -q -DforceStdout)
+        echo "Current selenium.version: $current_version"
+        # If version is in the form X.Y.Z, bump minor and set to SNAPSHOT
+        if [[ $current_version =~ ^([0-9]+)\.([0-9]+)\.([0-9]+)$ ]]; then
+          major="${BASH_REMATCH[1]}"
+          minor="${BASH_REMATCH[2]}"
+          next_minor=$((minor + 1))
+          new_version="$major.$next_minor.0-SNAPSHOT"
+          echo "Using selenium.version $new_version for tests"
+          cd examples/java
+          mvn -B -U test -D"jdk.internal.httpclient.disableHostnameVerification=true" -Dselenium.version=$new_version
+        fi
     - name: Run Tests Nightly Windows
       if: matrix.release == 'nightly' && matrix.os == 'windows'
-      uses: nick-invision/retry@v4.0.0
-      with:
-        timeout_minutes: 40
-        max_attempts: 3
-        command: |
-          # Get current selenium.version from Maven
-          $current_version = & mvn -f examples/java/pom.xml help:evaluate "-Dexpression=selenium.version" -q "-DforceStdout"
-          Write-Output "Current selenium.version: $current_version"
-          # If version is in the form X.Y.Z, bump minor and set to SNAPSHOT
-          if ($current_version -match '^([0-9]+)\.([0-9]+)\.([0-9]+)$') {
-            $major = $matches[1]
-            $minor = $matches[2]
-            $next_minor = [int]$minor + 1
-            $new_version = "$major.$next_minor.0-SNAPSHOT"
-            Write-Output "Using selenium.version $new_version for tests"
-            cd examples/java
-            mvn -B -U test "-Djdk.internal.httpclient.disableHostnameVerification=true" "-Dselenium.version=$new_version"
-          }
+      timeout-minutes: 40
+      run: |
+        # Get current selenium.version from Maven
+        $current_version = & mvn -f examples/java/pom.xml help:evaluate "-Dexpression=selenium.version" -q "-DforceStdout"
+        Write-Output "Current selenium.version: $current_version"
+        # If version is in the form X.Y.Z, bump minor and set to SNAPSHOT
+        if ($current_version -match '^([0-9]+)\.([0-9]+)\.([0-9]+)$') {
+          $major = $matches[1]
+          $minor = $matches[2]
+          $next_minor = [int]$minor + 1
+          $new_version = "$major.$next_minor.0-SNAPSHOT"
+          Write-Output "Using selenium.version $new_version for tests"
+          cd examples/java
+          mvn -B -U test "-Djdk.internal.httpclient.disableHostnameVerification=true" "-Dselenium.version=$new_version"
+        }
     - name: Upload test report
       uses: actions/upload-artifact@v7
       if: failure()

examples/dotnet/SeleniumDocs/BiDi/CDP/LoggingTest.cs

@@ -26,7 +26,7 @@ public async Task ConsoleLogs()
 
             driver.FindElement(By.Id("consoleLog")).Click();
             driver.FindElement(By.Id("consoleError")).Click();
-            new WebDriverWait(driver, TimeSpan.FromSeconds(5)).Until(_ => messages.Count > 1);
+            new WebDriverWait(driver, TimeSpan.FromSeconds(10)).Until(_ => messages.Count > 1);
             monitor.StopEventMonitoring();
 
             Assert.IsTrue(messages.Contains("Hello, world!"));

examples/dotnet/SeleniumDocs/Drivers/OptionsTest.cs

@@ -68,5 +68,19 @@ public void SetUnhandledPromptBehavior()
                 driver.Quit();
             }
         }
+        [TestMethod]
+        public void SetsProxy()
+        {
+            ChromeOptions options = new ChromeOptions();
+            Proxy proxy = new Proxy();
+            proxy.Kind = ProxyKind.Manual;
+            proxy.IsAutoDetect = false;
+            proxy.SslProxy = "myproxy.com:8080";
+            options.Proxy = proxy;
+            options.AddArgument("ignore-certificate-errors");
+
+            Assert.IsNotNull(options.Proxy);
+            Assert.AreEqual("myproxy.com:8080", options.Proxy.SslProxy);
+        }
     }
 }

examples/java/build.gradle

@@ -9,7 +9,7 @@ repositories {
     mavenCentral()
 }
 
-ext['seleniumVersion'] = System.getProperty('selenium.version', '4.47.0')
+ext['seleniumVersion'] = System.getProperty('selenium.version', '4.49.0')
 
 dependencies {
     testImplementation "org.seleniumhq.selenium:selenium-java:${seleniumVersion}"

examples/java/src/test/java/dev/selenium/bidirectional/webdriver_bidi/LogTest.java

@@ -97,7 +97,7 @@ void testRetrieveStacktraceForALog()
 
             StackTrace stackTrace = logEntry.getStackTrace();
             Assertions.assertNotNull(stackTrace);
-            Assertions.assertEquals(4, stackTrace.getCallFrames().size());
+            Assertions.assertEquals(3, stackTrace.getCallFrames().size());
         }
     }
 

examples/java/src/test/java/dev/selenium/drivers/OptionsTest.java

@@ -8,6 +8,7 @@
 import org.junit.jupiter.api.Test;
 import org.junit.jupiter.api.Assertions;
 import org.openqa.selenium.PageLoadStrategy;
+import org.openqa.selenium.Proxy;
 import org.openqa.selenium.UnexpectedAlertBehaviour;
 import org.openqa.selenium.WebDriver;
 import org.openqa.selenium.chrome.ChromeOptions;
@@ -169,5 +170,17 @@ public void setStrictFileInteractability() {
     Boolean capability = (Boolean) capabilityObject;
     Assertions.assertTrue(capability, "The capability STRICT_FILE_INTERACTABILITY should be set to true.");
   }
+
+  @Test
+  public void setsProxy() {
+    Proxy proxy = new Proxy();
+    proxy.setHttpProxy("myproxy.com:8080");
+    ChromeOptions options = getDefaultChromeOptions();
+    options.setCapability("proxy", proxy);
+
+    Object capabilityObject = options.getCapability("proxy");
+    Assertions.assertNotNull(capabilityObject, "Capability proxy should not be null.");
+    Assertions.assertEquals("myproxy.com:8080", ((Proxy) capabilityObject).getHttpProxy());
+  }
 }
 

examples/java/src/test/java/dev/selenium/grid/GettingStartedTest.java

@@ -0,0 +1,26 @@
+package dev.selenium.grid;
+
+import dev.selenium.BaseTest;
+import java.net.URL;
+import org.junit.jupiter.api.Test;
+import org.openqa.selenium.WebDriver;
+import org.openqa.selenium.chrome.ChromeOptions;
+import org.openqa.selenium.remote.RemoteWebDriver;
+
+public class GettingStartedTest extends BaseTest {
+
+  @Test
+  public void addsMetadataToASession() throws Exception {
+    URL gridUrl = startStandaloneGrid();
+
+    ChromeOptions chromeOptions = getDefaultChromeOptions();
+    // Showing a test name instead of the session id in the Grid UI
+    chromeOptions.setCapability("se:name", "My simple test");
+    // Other type of metadata can be seen in the Grid UI by clicking on the
+    // session info or via GraphQL
+    chromeOptions.setCapability("se:sampleMetadata", "Sample metadata value");
+    WebDriver driver = new RemoteWebDriver(gridUrl, chromeOptions);
+    this.driver = driver;
+    driver.get("https://www.selenium.dev");
+  }
+}

examples/java/src/test/java/dev/selenium/support/ThreadGuardTest.java

@@ -1,7 +1,29 @@
 package dev.selenium.support;
 
 import dev.selenium.BaseTest;
+import org.junit.jupiter.api.Assertions;
+import org.junit.jupiter.api.Test;
+import org.openqa.selenium.WebDriver;
+import org.openqa.selenium.support.ThreadGuard;
 
 public class ThreadGuardTest extends BaseTest {
 
+  @Test
+  public void protectsDriverFromCrossThreadUse() throws InterruptedException {
+    WebDriver protectedDriver = ThreadGuard.protect(startChromeDriver());
+
+    Throwable[] caughtOnOtherThread = new Throwable[1];
+    Runnable callFromOtherThread = () -> {
+      try {
+        protectedDriver.get("https://www.selenium.dev");
+      } catch (Throwable t) {
+        caughtOnOtherThread[0] = t;
+      }
+    };
+    Thread otherThread = new Thread(callFromOtherThread);
+    otherThread.start();
+    otherThread.join();
+
+    Assertions.assertNotNull(caughtOnOtherThread[0]);
+  }
 }

examples/java/src/test/java/dev/selenium/test_practices/DomainSpecificLanguageExample.java

@@ -0,0 +1,59 @@
+package dev.selenium.test_practices;
+
+import org.junit.jupiter.api.Disabled;
+import org.junit.jupiter.api.Test;
+import org.openqa.selenium.By;
+import org.openqa.selenium.WebDriver;
+import org.openqa.selenium.WebElement;
+import org.openqa.selenium.chrome.ChromeDriver;
+import org.openqa.selenium.support.PageFactory;
+
+class AccountPage {
+}
+
+class LoginPage {
+  private final WebDriver driver;
+
+  public LoginPage(WebDriver driver) {
+    this.driver = driver;
+  }
+
+  /**
+   * Takes a username and password, fills out the fields, and clicks "login".
+   *
+   * @return An instance of the AccountPage
+   */
+  public AccountPage loginAsUser(String username, String password) {
+    WebElement loginField = driver.findElement(By.id("loginField"));
+    loginField.clear();
+    loginField.sendKeys(username);
+
+    // Fill out the password field. The locator we're using is "By.id", and we should
+    // have it defined elsewhere in the class.
+    WebElement passwordField = driver.findElement(By.id("password"));
+    passwordField.clear();
+    passwordField.sendKeys(password);
+
+    // Click the login button, which happens to have the id "submit".
+    driver.findElement(By.id("submit")).click();
+
+    // Create and return a new instance of the AccountPage (via the built-in Selenium
+    // PageFactory).
+    return PageFactory.initElements(driver, AccountPage.class);
+  }
+}
+
+public class DomainSpecificLanguageExample {
+
+  @Test
+  @Disabled("Illustrative only: LoginPage targets a fictional application, not a live site")
+  void loginAsUserAbstractsTheLoginFormFromTheTest() {
+    WebDriver driver = new ChromeDriver();
+    try {
+      LoginPage loginPage = new LoginPage(driver);
+      loginPage.loginAsUser("cbrown", "cl0wn3");
+    } finally {
+      driver.quit();
+    }
+  }
+}

examples/java/src/test/java/dev/selenium/test_practices/FluentApiExample.java

@@ -0,0 +1,51 @@
+package dev.selenium.test_practices;
+
+import java.time.Duration;
+import org.junit.jupiter.api.Disabled;
+import org.junit.jupiter.api.Test;
+import org.openqa.selenium.By;
+import org.openqa.selenium.WebDriver;
+import org.openqa.selenium.chrome.ChromeDriver;
+import org.openqa.selenium.support.ui.WebDriverWait;
+
+abstract class BasePage {
+  protected WebDriver driver;
+
+  public BasePage(WebDriver driver) {
+    this.driver = driver;
+  }
+}
+
+class GoogleSearchPage extends BasePage {
+  public GoogleSearchPage(WebDriver driver) {
+    super(driver);
+    // Generally do not assert within pages or components.
+    // Effectively throws an exception if the lambda condition is not met.
+    new WebDriverWait(driver, Duration.ofSeconds(3)).until(d -> d.findElement(By.id("logo")));
+  }
+
+  public GoogleSearchPage setSearchString(String sstr) {
+    driver.findElement(By.id("gbqfq")).sendKeys(sstr);
+    return this;
+  }
+
+  public void clickSearchButton() {
+    driver.findElement(By.id("gbqfb")).click();
+  }
+}
+
+public class FluentApiExample {
+
+  @Test
+  @Disabled("Illustrative only: targets Google's live, frequently changing search page markup")
+  void queryTheGoogleSearchPageUsingAFluentApi() {
+    WebDriver driver = new ChromeDriver();
+    try {
+      driver.get("http://www.google.com/webhp?hl=en&tab=ww");
+      GoogleSearchPage gsp = new GoogleSearchPage(driver);
+      gsp.setSearchString("cheese").clickSearchButton();
+    } finally {
+      driver.quit();
+    }
+  }
+}

examples/java/src/test/java/dev/selenium/test_practices/FreshBrowserPerTestTest.java

@@ -0,0 +1,15 @@
+package dev.selenium.test_practices;
+
+import dev.selenium.BaseTest;
+import org.junit.jupiter.api.Test;
+import org.openqa.selenium.WebDriver;
+import org.openqa.selenium.firefox.FirefoxDriver;
+
+public class FreshBrowserPerTestTest extends BaseTest {
+
+  @Test
+  public void startsAFreshBrowserForTheTest() {
+    WebDriver driver = new FirefoxDriver();
+    this.driver = driver;
+  }
+}

examples/javascript/test/drivers/options.spec.js

@@ -0,0 +1,14 @@
+const chrome = require('selenium-webdriver/chrome')
+const proxy = require('selenium-webdriver/proxy')
+const assert = require('node:assert')
+
+describe('Options Test', function () {
+  it('Sets proxy', function () {
+    const options = new chrome.Options()
+    options.setProxy(proxy.manual({ http: 'myproxy.com:8080' }))
+
+    const capability = options.getProxy()
+    assert.notStrictEqual(capability, undefined)
+    assert.strictEqual(capability.httpProxy, 'myproxy.com:8080')
+  })
+})

examples/kotlin/src/test/kotlin/dev/selenium/drivers/OptionsTest.kt

@@ -0,0 +1,22 @@
+package dev.selenium.drivers
+
+import dev.selenium.BaseTest
+import org.junit.jupiter.api.Assertions
+import org.junit.jupiter.api.Test
+import org.openqa.selenium.Proxy
+import org.openqa.selenium.chrome.ChromeOptions
+
+class OptionsTest : BaseTest() {
+
+    @Test
+    fun setsProxy() {
+        val proxy = Proxy()
+        proxy.setHttpProxy("myproxy.com:8080")
+        val options = ChromeOptions()
+        options.setCapability("proxy", proxy)
+
+        val capabilityObject = options.getCapability("proxy") as Proxy
+        Assertions.assertNotNull(capabilityObject)
+        Assertions.assertEquals("myproxy.com:8080", capabilityObject.httpProxy)
+    }
+}