Stop Selenium from running against the wrong environment

A scheduled smoke job reports green, and the cleanup step it ran has just deleted fixture data in QA. Nobody asked for QA. That job never set TEST_ENV at all, and a forgiving configuration helper caught the resulting error and returned its QA fallback. Selenium did exactly what it was told; the framework picked the target before the first browser session existed, and the destructive step inherited that choice without ever being told which system it was pointed at.

Typed configuration is useful because environment selection is a closed decision. A run may target local, QA, staging, or production, but it should not manufacture a target from an absent variable or a spelling mistake. The enum is only one part of the solution. The important work is validating external input, keeping mutable deployment details out of constants, exposing the effective choice, and refusing unsafe combinations before a driver is created.

Model the decisions that must stay fixed for one run

An environment name usually carries two kinds of information, and mixing them creates trouble. Stable policy changes slowly: whether destructive tests are allowed, which application identity is expected, and whether the target is considered production. Deployment data changes often: a Grid address, credentials, a release identifier, a proxy, or a temporary review-app URL. An enum is a good home for the first group. It is a poor secret store and an awkward service-discovery mechanism for the second.

That distinction matters during incident review. If QA always means the same safety policy but its Grid URL comes from the job, a reviewer can see whether the bad choice came from source code or deployment wiring. If an enum constant contains a username, token, mutable endpoint, browser instance, or options object, its meaning changes while the Java type still suggests that it is permanent. The code becomes harder to reason about, particularly when JUnit runs tests concurrently.

Keep each constant declarative. The following enum owns the application origin, the expected deployment label, and the permission to mutate data. The parser accepts ordinary differences in case and surrounding whitespace, but it never guesses after an unrecognized value. A typo can therefore fail before any Selenium session or application request is made.

import java.net.URI;
import java.util.Arrays;
import java.util.Locale;
import java.util.stream.Collectors;

public enum TestEnvironment {
    LOCAL("http://127.0.0.1:3000", "local", true),
    QA("https://qa.example.test", "qa", true),
    STAGING("https://staging.example.test", "staging", true),
    PRODUCTION("https://www.example.test", "production", false);

    private final URI applicationOrigin;
    private final String expectedDeployment;
    private final boolean destructiveTestsAllowed;

    TestEnvironment(
            String applicationOrigin,
            String expectedDeployment,
            boolean destructiveTestsAllowed) {
        this.applicationOrigin = URI.create(applicationOrigin);
        this.expectedDeployment = expectedDeployment;
        this.destructiveTestsAllowed = destructiveTestsAllowed;
    }

    public URI applicationOrigin() {
        return applicationOrigin;
    }

    public String expectedDeployment() {
        return expectedDeployment;
    }

    public boolean destructiveTestsAllowed() {
        return destructiveTestsAllowed;
    }

    public static TestEnvironment parse(String raw) {
        if (raw == null || raw.isBlank()) {
            throw new IllegalArgumentException("TEST_ENV is required");
        }

        String normalized = raw.trim().toUpperCase(Locale.ROOT);
        try {
            return TestEnvironment.valueOf(normalized);
        } catch (IllegalArgumentException error) {
            String allowed = Arrays.stream(values())
                    .map(value -> value.name().toLowerCase(Locale.ROOT))
                    .collect(Collectors.joining(", "));
            throw new IllegalArgumentException(
                    "Unsupported TEST_ENV '" + raw + "'. Allowed: " + allowed,
                    error);
        }
    }
}

There is a deliberate judgment in that parser. Whitespace and letter case do not change an operator's likely intent, so normalizing them is reasonable. Mapping preprod, stage, and stg to the same constant is a different decision. Aliases can be useful during a migration, but an undocumented alias makes configuration history difficult to read. If aliases are needed, list them explicitly and test them. Do not use substring matching such as startsWith("prod"); production-copy and prod-debug may have safety requirements that differ from production.

The values returned by System.getenv and System.getProperty are inputs, not configuration objects. Read them at the suite boundary and create one immutable run configuration. Passing that object to factories and fixtures prevents one test from changing a process-wide property while another test is opening a session. It also makes a test's dependencies visible in its constructor rather than hiding them behind calls scattered across page objects.

A practical run configuration should record the selected environment, browser, optional Grid address, run identifier, and the caller's explicit permission for sensitive operations. It should not log a token merely because the token was present in the same environment map. Copy only named, non-secret fields into diagnostic output.

The phrase Java enum Selenium environment configuration sometimes encourages teams to put every setting inside the enum. Resist that interpretation. The enum closes the set of supported targets. The run object combines that choice with values supplied for this execution. Those are separate responsibilities, and keeping them separate is what makes the type useful.

Reject ambiguous input before WebDriver starts

Fail-fast validation saves more than browser startup time. It prevents a misleading automation failure from hiding a configuration error. A NoSuchElementException on the login page may really mean the test opened an older deployment. A session-creation timeout may mean the Grid URL points to an application load balancer. Once WebDriver is involved, both mistakes acquire stack traces that tempt people to debug the wrong layer.

Choose one authoritative input name. If a Maven property, Gradle property, dotenv file, and CI variable can all select the target, publish a precise precedence rule and log which source won. A safer default is to translate those sources in the build wrapper, then give Java one TEST_ENV value. Do not let an absent CI variable silently become staging. Local convenience is not worth a production-facing ambiguity.

This loader validates values without creating a driver. It also requires a positive production guard for any production run, even though the enum already marks production as read-only. The two controls answer different questions. The constant says what the framework permits. The guard proves that the operator intended to enter the sensitive environment at all.

import java.net.URI;
import java.util.Locale;
import java.util.Map;
import java.util.Objects;
import java.util.Optional;

public record RunConfiguration(
        TestEnvironment environment,
        Browser browser,
        Optional<URI> gridUrl,
        String runId,
        boolean productionApproved) {

    public enum Browser { CHROME, FIREFOX }

    public static RunConfiguration from(Map<String, String> input) {
        Objects.requireNonNull(input, "input");
        TestEnvironment environment = TestEnvironment.parse(input.get("TEST_ENV"));
        Browser browser = parseBrowser(input.getOrDefault("BROWSER", "chrome"));
        Optional<URI> gridUrl = optionalHttpUri(input.get("SELENIUM_GRID_URL"));
        String runId = requireText(input, "RUN_ID");
        boolean productionApproved = "true".equalsIgnoreCase(
                input.getOrDefault("ALLOW_PRODUCTION", "false").trim());

        if (environment == TestEnvironment.PRODUCTION && !productionApproved) {
            throw new IllegalArgumentException(
                    "Production selected without ALLOW_PRODUCTION=true");
        }

        return new RunConfiguration(
                environment, browser, gridUrl, runId, productionApproved);
    }

    private static Browser parseBrowser(String raw) {
        try {
            return Browser.valueOf(raw.trim().toUpperCase(Locale.ROOT));
        } catch (RuntimeException error) {
            throw new IllegalArgumentException(
                    "BROWSER must be chrome or firefox, received '" + raw + "'",
                    error);
        }
    }

    private static Optional<URI> optionalHttpUri(String raw) {
        if (raw == null || raw.isBlank()) {
            return Optional.empty();
        }
        URI uri = URI.create(raw.trim());
        if (!"http".equals(uri.getScheme()) && !"https".equals(uri.getScheme())) {
            throw new IllegalArgumentException(
                    "SELENIUM_GRID_URL must use http or https");
        }
        if (uri.getHost() == null) {
            throw new IllegalArgumentException(
                    "SELENIUM_GRID_URL must include a host");
        }
        return Optional.of(uri);
    }

    private static String requireText(Map<String, String> input, String key) {
        String value = input.get(key);
        if (value == null || value.isBlank()) {
            throw new IllegalArgumentException(key + " is required");
        }
        return value.trim();
    }
}

The URI validation is intentionally modest. It checks the shape that the driver factory can use, not whether a server is currently reachable. Network probing in a constructor makes unit tests slow and introduces time-dependent behavior. Reachability belongs in a CI preflight with an explicit timeout. Session creation remains the final proof that Grid can match the requested browser options.

An enum does not make a configuration correct by itself. Its value comes from the invalid states that surrounding code refuses to represent. The loader above can reject a missing run ID, an unsupported browser, a malformed Grid scheme, and an unapproved production selection. Each rejection happens without opening a browser. A change to any of those constraints will make the corresponding test fail, so the tests are genuine oracles rather than assertions over fixtures that cannot vary.

import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertThrows;
import static org.junit.jupiter.api.Assertions.assertTrue;

import java.util.HashMap;
import java.util.Map;
import org.junit.jupiter.api.Test;

class RunConfigurationTest {
    @Test
    void trimsAndParsesAnExplicitEnvironment() {
        Map<String, String> input = new HashMap<>();
        input.put("TEST_ENV", " qa ");
        input.put("RUN_ID", "build-1842");

        RunConfiguration config = RunConfiguration.from(input);

        assertEquals(TestEnvironment.QA, config.environment());
        assertEquals(RunConfiguration.Browser.CHROME, config.browser());
        assertTrue(config.gridUrl().isEmpty());
    }

    @Test
    void rejectsAnUnknownEnvironmentInsteadOfFallingBack() {
        Map<String, String> input = Map.of(
                "TEST_ENV", "qu",
                "RUN_ID", "build-1843");

        IllegalArgumentException error = assertThrows(
                IllegalArgumentException.class,
                () -> RunConfiguration.from(input));

        assertTrue(error.getMessage().contains("Unsupported TEST_ENV 'qu'"));
    }

    @Test
    void requiresASeparateProductionApproval() {
        Map<String, String> input = Map.of(
                "TEST_ENV", "production",
                "RUN_ID", "build-1844");

        IllegalArgumentException error = assertThrows(
                IllegalArgumentException.class,
                () -> RunConfiguration.from(input));

        assertEquals(
                "Production selected without ALLOW_PRODUCTION=true",
                error.getMessage());
    }
}

Notice what the tests do not assert. They do not check that a hard-coded enum constant equals itself. They drive variable input through the public parser and prove that a dangerous change, such as adding a default for qu, would be caught. Add similar cases for every alias or safety rule that your organization decides to support.

Create the driver from one immutable configuration

Browser options are session requests. With a remote session, the Grid matches that request to an available node and returns the effective capabilities for the new session. Selenium's Grid documentation shows RemoteWebDriver receiving a Grid URL and an options object, while the WebDriver specification defines standard capabilities such as browser name, browser version, platform name, and acceptInsecureCerts. That is why a driver factory should create a fresh options object for every session and preserve the returned capability data for diagnosis.

Do not cache ChromeOptions, FirefoxOptions, or a driver in an enum constant. A test may add an argument or capability and contaminate the next session. Shared mutable driver state is even more dangerous under parallel execution. An enum constant is a singleton within its class loader, so anything reachable and mutable from it can become accidental suite-wide state.

This factory uses the run configuration but creates new options on every call. It places a non-secret run ID in Selenium Grid metadata through an se: extension capability, as documented by Selenium's Grid guide. Local execution remains possible when no Grid URL is supplied. The return type is RemoteWebDriver, which is valid for the local Chrome and Firefox driver classes as well as for a remote session.

import java.net.MalformedURLException;
import org.openqa.selenium.MutableCapabilities;
import org.openqa.selenium.chrome.ChromeDriver;
import org.openqa.selenium.chrome.ChromeOptions;
import org.openqa.selenium.firefox.FirefoxDriver;
import org.openqa.selenium.firefox.FirefoxOptions;
import org.openqa.selenium.remote.RemoteWebDriver;

public final class DriverFactory {
    private DriverFactory() {}

    public static RemoteWebDriver open(RunConfiguration config) {
        MutableCapabilities options = switch (config.browser()) {
            case CHROME -> new ChromeOptions();
            case FIREFOX -> new FirefoxOptions();
        };
        if (config.gridUrl().isEmpty()) {
            return switch (config.browser()) {
                case CHROME -> new ChromeDriver((ChromeOptions) options);
                case FIREFOX -> new FirefoxDriver((FirefoxOptions) options);
            };
        }

        try {
            options.setCapability("se:name", config.runId());
            return new RemoteWebDriver(config.gridUrl().orElseThrow().toURL(), options);
        } catch (MalformedURLException error) {
            throw new IllegalArgumentException("Invalid Selenium Grid URL", error);
        }
    }
}

The cast is safe here because the switch created the matching concrete options type in the same method. A different design can avoid casts with two private factory methods. What matters is that the browser choice is exhaustive. Adding EDGE to the enum forces the compiler to identify switches that have not decided how Edge should be created.

Returned capabilities are evidence, not a second configuration source. Log the requested browser and the returned browser name, version, and platform after session creation. Do not copy the entire capability map into a public artifact without review because vendor extension capabilities may contain operational data. A compact line such as run=build-1842 env=qa requestedBrowser=chrome actualBrowser=chrome version=... platform=... lets a failed job be correlated with the Grid UI without exposing credentials.

The product assertion must go beyond successful session creation. Navigation only proves that the browser reached some document. Selenium exposes the current URL, and the WebDriver specification defines that command as returning the active document's URL. Compare its parsed host with the configured host, then query a safe deployment marker in the application UI or through a test-owned endpoint. A reverse proxy can serve the wrong release on the right host, so those checks catch different faults.

Avoid startsWith for host validation. https://qa.example.test.attacker.invalid starts with the expected text but is not the expected origin. Parse both values as URIs and compare scheme, host, and effective port according to your redirect policy. If the application intentionally redirects from HTTP to HTTPS or from a bare host to www, encode that exact allowance rather than weakening the check to a substring.

Tell configuration faults from Grid and application faults

Start diagnosis with the last boundary that completed. If configuration parsing throws, no Selenium session should exist. If the Grid status endpoint is unreachable, the problem precedes capability matching. If session creation fails while Grid status is healthy, inspect the requested browser, version, platform, and the Grid's available slots. If navigation succeeds but the deployment marker differs, the Grid worked and the target application routing is wrong.

The exception class alone is not enough. A session creation failure can come from an unavailable browser slot, an invalid remote address, a driver startup problem, or another Grid-side condition. Preserve the original exception and pair it with the validated configuration snapshot. Do not replace it with Could not start browser, which discards the part of the message that an operator needs.

Run a short preflight before the Java test command. The script below validates only non-secret values and checks the Grid status endpoint when remote execution is requested. It deliberately does not probe the application from the Java client host. A successful client-side request would not prove that a remote browser node has the same DNS, proxy, or network path; the WebDriver navigation and deployment marker provide that evidence from the browser itself.

#!/usr/bin/env bash
set -euo pipefail

: "${TEST_ENV:?TEST_ENV must be set}"
: "${RUN_ID:?RUN_ID must be set}"

trim_whitespace() {
  local value="$1"
  value="${value#"${value%%[![:space:]]*}"}"
  value="${value%"${value##*[![:space:]]}"}"
  printf '%s' "$value"
}

trimmed_env=$(trim_whitespace "$TEST_ENV")
normalized_env=$(printf '%s' "$trimmed_env" | tr '[:upper:]' '[:lower:]')
case "${normalized_env}" in
  local|qa|staging|production) ;;
  *) printf 'Unsupported TEST_ENV: %s\n' "${TEST_ENV}" >&2; exit 2 ;;
esac

raw_allow_production="${ALLOW_PRODUCTION:-false}"
trimmed_allow_production=$(trim_whitespace "$raw_allow_production")
normalized_allow_production=$(
  printf '%s' "$trimmed_allow_production" | tr '[:upper:]' '[:lower:]'
)
if [[ "${normalized_env}" == "production" && "${normalized_allow_production}" != "true" ]]; then
  printf 'Production requires ALLOW_PRODUCTION=true\n' >&2
  exit 2
fi

if [[ -n "${SELENIUM_GRID_URL:-}" ]]; then
  curl --fail --silent --show-error \
    --connect-timeout 3 --max-time 10 \
    "${SELENIUM_GRID_URL%/}/status" >/dev/null
fi

printf 'preflight ok run=%s env=%s browser=%s remote=%s\n' \
  "${RUN_ID}" "${normalized_env}" "${BROWSER:-chrome}" \
  "$([[ -n "${SELENIUM_GRID_URL:-}" ]] && printf yes || printf no)"

The preflight now trims and folds case for TEST_ENV and ALLOW_PRODUCTION, matching the Java parser's accepted forms such as qa and TRUE. It uses tr instead of Bash 4's ${name,,} expansion, so the script also runs under the Bash 3.2 supplied with macOS.

Treat the script's output as controlled diagnostic output because your own code defines it. By contrast, do not write an article or parser that depends on one exact Selenium exception sentence across every binding and browser version. Preserve the full exception, classify it using the failed boundary, and assert only stable details in framework tests.

A wrong-host failure has distinctive evidence. The configuration log says env=qa, the requested origin is QA, session creation succeeds, and getCurrentUrl() reports a staging host. That points toward a redirect, DNS, proxy, or application routing issue after configuration. If the configuration log itself says env=staging, investigate input selection instead. The same final screenshot can appear in both cases, but the first divergent record is different.

An unavailable Grid can look similar when a wrapper catches every startup exception and launches a local browser as a fallback. Remove that fallback in CI. A local fallback changes network reachability, browser version, operating system, and artifact location, so the passing retry no longer answers whether the remote configuration works. If local fallback is useful for developers, require an explicit EXECUTION_MODE=local and include it in the run summary.

An application authentication failure is another near-miss. A test may land on the correct QA host and see a login page because its token was issued for staging. The enum selected the right application but the credential audience is wrong. Compare the URL host and non-secret deployment marker first, then inspect the authentication response without logging the token. Changing the environment parser cannot repair a credential issued for another audience.

Work through failures that produce deceptively similar screenshots

Consider a cleanup test that is allowed in QA and staging but forbidden in production. This is the incident from the opening, written out in full. The old framework calls System.getenv("TEST_ENV"), catches any exception, and returns QA. A scheduled production smoke job forgets the variable, so the browser opens QA and deletes the fixture successfully. Every UI assertion passes. The actual defect is not flakiness; it is an absent required input coupled to a destructive fallback. Note that the fallback constant and the damaged environment are necessarily the same one, which is what makes the report so confusing: the job's own log says QA, and QA is exactly where the deletion landed, so nothing in the artifact looks contradictory until somebody asks why a production smoke job wrote to QA at all.

The fixed path has three independent barriers. RunConfiguration.from rejects the missing environment. Production requires explicit approval. The fixture checks destructiveTestsAllowed() before it creates data. None of these replaces deployment access controls, but each catches a different automation mistake. The cost is additional setup in every job. That cost is worthwhile because a new job cannot inherit a dangerous target by accident.

Now consider a suite that reports qa but opens staging intermittently during parallel execution. The framework stores a mutable static currentEnvironment. One parameterized class changes it in beforeAll, another class changes it moments later, and page objects consult the field lazily. Both values are valid enum constants, so parsing tests stay green. Evidence from a failing run shows the run-level log as QA, followed by a page-object log that constructs a staging URL.

The repair is ownership, not more enum validation. Build one immutable RunConfiguration for each test plan or invocation and inject it into every component that needs a URL. If a single JVM intentionally runs multiple environments at once, scope the object to the test instance and never consult mutable global state. A ThreadLocal may hide the race for one execution model, but it introduces lifecycle and cleanup obligations and breaks when work moves between threads. Explicit parameters are dull, visible, and reliable.

A third case begins with a healthy QA application and a healthy Grid status endpoint, yet remote session creation fails. The configuration requests Firefox on Linux while the current Grid only advertises Chrome slots. Changing the application environment or increasing a navigation timeout cannot help because navigation never began. Compare the validated request with Grid capacity, then either provision the intended browser or change the declared browser matrix. Do not quietly substitute Chrome, since that turns a missing Firefox result into a misleading green build.

There is also a common redirect near-miss. The application origin is correct, but the identity provider redirects through a shared login host before returning. An assertion that checks the host immediately after driver.get may fail on a legitimate intermediate document, especially if the test does not wait for the application to regain control. Wait for a product-specific element or final callback condition, then compare the final origin. The expected deployment marker should be read only after that transition. This is an application flow issue, not evidence that enum parsing failed.

For every case, write down the sequence rather than just the final symptom: input received, configuration accepted, session requested, capabilities returned, navigation requested, current URL observed, deployment identity observed, and product assertion evaluated. Missing steps show where instrumentation is needed. Conflicting values show the first boundary at which the run departed from its declared intent.

Roll the change into an existing suite without hiding regressions

Begin with observation. Add a single run summary to the existing framework before changing selection behavior. Record the current raw environment value, normalized environment, browser, remote or local mode, application origin, run ID, and production safety state. Redact query strings and never log secrets. A few days of CI artifacts will reveal aliases, blank defaults, and jobs that depend on undocumented precedence.

Next, create parsing tests from values that actually appear in build definitions. Mark every accepted alias as temporary or permanent. If stage and staging both exist, either support both explicitly or migrate one job at a time. Emit a deprecation warning for a temporary alias with the job name and removal date. Silent normalization makes it impossible to know when the old spelling can be deleted.

Introduce the immutable run configuration behind the existing driver factory. Keep page objects unaware of environment names; give them an application origin or a navigation helper derived from the configuration. This limits the migration surface. A page object should know how to operate a page, not whether qa-eu maps to a particular host.

Turn missing input into an error in non-production jobs first. Teams often discover developer scripts that relied on a default. Provide an explicit local launcher that sets TEST_ENV=local rather than restoring the implicit default in shared code. Once all callers declare a target, enable the same rule everywhere and add the production approval check.

Run old and new selection logic side by side for a short comparison period, but let only the old path drive the browser until discrepancies are understood. Log legacyTarget and typedTarget; fail a dedicated configuration contract test when they differ in protected branches. Do not run duplicate destructive tests against two environments. The comparison belongs before session creation.

After the typed path becomes authoritative, remove writable global setters and fallback branches. Leaving them available invites new code to bypass the model. A compile error at a former call site is useful migration evidence because it identifies a component whose configuration ownership was hidden.

Finally, add an application identity assertion to a small smoke test that runs before destructive or expensive suites. The marker should be intentionally exposed for automation, non-secret, and tied to the deployed environment or release. If no such marker exists, ask the application team for one instead of inferring identity from branding text. Shared page copy is not a deployment identifier.

The rollout increases configuration code and requires CI owners to set explicit variables. It may also stop jobs that used to limp forward under defaults. Treat those failures as discovered risk, not as regressions to suppress. The framework is revealing that nobody could previously prove which system those jobs exercised.

Know what the enum costs and when not to use it

Closed sets trade flexibility for safety. Adding a permanent environment now requires a code change, review, and release of the test framework. That delay is valuable for QA, staging, and production targets with distinct safety policy. It is frustrating for ephemeral preview environments whose hostnames are created for every pull request. Do not add one enum constant per preview deployment.

For previews, model the policy as an enum such as PREVIEW, then supply a validated URI and expected deployment identifier at runtime. Restrict the allowed hostname suffix, require HTTPS where appropriate, and decide whether destructive tests are permitted. The string remains dynamic, but the risk category stays typed. An enum is also unnecessary when a suite has exactly one fixed target and deployment injects the origin without any behavioral difference. A well-validated URI may be the simpler design.

Avoid the pattern when different environment values can be discovered from a service catalog and change independently of the test code. A registry client with a validated response and cached snapshot may express that model better. Still capture the resolved target in the run artifact. Dynamic discovery should make changes easier, not make a completed run impossible to reconstruct.

The driver factory also has a maintenance cost. Every supported browser needs a branch, relevant options, and matrix coverage. Exhaustive switches make missing decisions visible, but they do not prove that Grid has the requested capacity. Keep a small session-creation contract test for each supported combination and run it when the Grid image or browser matrix changes.

Strict validation can reduce developer convenience. Someone running one test from an IDE must supply a run ID and environment. Solve that with a checked-in IDE example or a local wrapper that provides explicit safe values. Do not solve it by teaching production code to guess. Convenience should be visible at the invocation boundary.

Do not use environment selection as the only protection against production damage. Server-side authorization, isolated accounts, rate limits, and test-data policy still matter. A Java enum cannot stop a credential from having excessive privileges, and an ALLOW_PRODUCTION string is not an approval system. These controls make automation intent explicit and failures diagnosable; they do not replace controls owned by the product and platform.

Finally, resist adding a configuration abstraction when the real problem is deployment inconsistency. If the QA hostname sometimes serves staging because of a proxy rule, a richer enum will only label the wrong response more elegantly. Preserve the requested target, returned session details, final URL, and deployment marker. That evidence tells the platform owner what diverged and keeps the automation fix focused on the boundary it actually owns.