java/TESTING.md

# Java Testing Guide

This guide helps contributors write tests in the Selenium Java codebase.

## Test Framework

* Browser tests use JUnit 5 (Jupiter) and extend `JupiterTestBase`.
* Test HTML pages live in `common/src/web/`.
* `pages` field gets URLs from `java/test/org/openqa/selenium/testing/Pages.java`.
* There are 2 pre-configured wait methods for 5 seconds and 10 seconds.
* Assertions use the AssertJ library.

```java
class MyFeatureTest extends JupiterTestBase {
    @Test
    void testBasicFunctionality() {
        driver.get(pages.xhtmlTestPage);

        wait.until(ExpectedConditions.titleIs("XHTML Test Page"));  // 10s timeout
        shortWait.until(ExpectedConditions.elementToBeClickable(element));  // 5s timeout

        assertThat(driver.getTitle()).isEqualTo("XHTML Test Page");
    }

    @Test
    void testWithLocalDriver() {
        localDriver = new ChromeDriver();
        localDriver.get(pages.xhtmlTestPage);
        wait(localDriver).until(ExpectedConditions.titleIs("XHTML Test Page"));  // creates 10s wait
    }
}
```

## Running Tests

Bazel creates separate test targets for browsers and remote grid depending on 
what is supported in the `BUILD.bazel` file in that test's directory.
Tests run in parallel by default.

```shell
bazel test //java/...  # Run all Java tests
bazel test //java/test/org/openqa/selenium/bidi/... # Run all tests in bidi directory
bazel test //java/test/org/openqa/selenium/chrome:ChromeDriverFunctionalTest # Run a specific test

# Test Filters
bazel test //java/... --test_size_filters=small   # unit tests only (no browser)
bazel test //java/... --test_size_filters=large   # all browser tests
bazel test //java/... --test_tag_filters=chrome   # chrome tests only
bazel test //java/... --test_tag_filters=remote-browser  # all browser tests that run on grid
bazel test //java/... --test_tag_filters=-safari  # no safari tests (use `-` to exclude a tag)

# Additional Arguments
bazel test //java/... --pin_browsers  # Use pinned browser versions (recommended)
bazel test //java/... --flaky_test_attempts=3 # Rerun failed tests up to 3 times
bazel test //java/... --test_output=all # displays all test output at end of run
bazel test //java/... --test_output=streamed # displays test output in real time (disables parallel execution)
```

## Annotations

Valid Browser values: `CHROME`, `EDGE`, `FIREFOX`, `SAFARI`, `IE`, `ALL`. (Default is `ALL`)

### Skipping and Expected Failures

These accept parameters for `value` (browser name) and `reason`. Each browser on a separate line.

| Annotation | When to Use                                                                                                                                   |
|------------|-----------------------------------------------------------------------------------------------------------------------------------------------|
| `@Ignore` | Test doesn't work for a browser. Also accepts `issue` (GitHub issue, e.g. `"#1234"`) and `gitHubActions` (only skip on CI).                   |
| `@NotYetImplemented` | Feature isn't implemented yet. Test always runs and passes if it fails, and fails if it unexpectedly passes so the annotation can be removed. |

### Driver Lifecycle

The shared `driver` is reused across tests for efficiency. These annotations control that behavior. They accept `value` (browser) and `reason`.

| Annotation | When to Use                                                                                                                                              |
|------------|----------------------------------------------------------------------------------------------------------------------------------------------------------|
| `@NeedsFreshDriver` | Test needs clean browser state with default capabilities. Driver is restarted before the test.                                                           |
| `@NoDriverBeforeTest` | Test needs custom capabilities or tests driver creation itself. Driver is destroyed, must use `createNewDriver(capabilities)` in the test to create one. |
| `@NoDriverAfterTest` | Test leaves browser in a bad state. Driver is restarted after the test. Also accepts `failedOnly`.                                                       |

For tests needing two browsers simultaneously (e.g., multi-user scenarios), create a second instance with `localDriver = new ChromeDriver()`. This driver is automatically quit after the test.

If `createNewDriver(capabilities)` is called without an annotation, it closes the current driver and creates a new one.

*Be careful with hard-coding the creation of new drivers since it may conflict with the current Bazel target.*

### Other

| Annotation | When to Use |
|------------|-------------|
| `@SwitchToTopAfterTest` | Test navigates into frames. Automatically switches to default content after. |
| `@NeedsSecureServer` | Class-level. All tests in the class need HTTPS. |

## Build files

* Adding tests shouldn't require changes in Bazel files since most are picked up automatically. 
* Make sure the `*Test.java` file is in a directory that has a `BUILD.bazel` file with a `java_selenium_test_suite` declaration.