feat(driver): maximize headed local browsers by default

CHANGELOG.md

@@ -9,6 +9,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ### Unreleased
 
+- **Headed local browsers start maximized by default** — Chrome gets `--start-maximized` and Firefox calls `maximize()` after launch, so a watched test is no longer left in a small window. Headless runs and containers (fixed 1920x1080) are unchanged, and your own `--start-maximized`, `--window-size`, `--kiosk` or Firefox `--width`/`--height` arguments still win.
+
 - **HTML report: sortable columns in Test Cases table** — clicking headers for Test, Status, Logic (ms), and Total (ms) sorts rows within each test class group ascending or descending with visual sort indicators, while preserving detail row attachments and cooperating seamlessly with active status, tag, and search filters. (#217)
 
 ### v3.10.0 — 2026-11-04

src/main/java/com/seleniumboot/driver/LocalChromeDriverProvider.java

@@ -48,6 +48,12 @@ public WebDriver createDriver() {
             );
         }
 
+        // Headed local runs start maximized unless the size is already decided (see WindowSizing).
+        if (WindowSizing.shouldMaximize(config.getBrowser().isHeadless(),
+                CiEnvironmentDetector.isContainer(), arguments)) {
+            options.addArguments("--start-maximized");
+        }
+
         if (arguments != null) {
             options.addArguments(arguments);
         }

src/main/java/com/seleniumboot/driver/LocalFirefoxDriverProvider.java

@@ -74,6 +74,11 @@ public WebDriver createDriver() {
         }
 
         WebDriver driver = new FirefoxDriver(options);
+        // Firefox has no start-maximized flag; maximize once the window exists (see WindowSizing).
+        if (WindowSizing.shouldMaximize(config.getBrowser().isHeadless(),
+                CiEnvironmentDetector.isContainer(), arguments)) {
+            driver.manage().window().maximize();
+        }
         driver.manage().timeouts().implicitlyWait(Duration.ZERO);
 
         driver.manage().timeouts().pageLoadTimeout(Duration.ofSeconds(config.getTimeouts().getPageLoad()));

src/main/java/com/seleniumboot/driver/WindowSizing.java

@@ -0,0 +1,34 @@
+package com.seleniumboot.driver;
+
+import java.util.List;
+
+/**
+ * Decides whether a locally launched, visible browser should start maximized.
+ *
+ * <p>Maximizing is the default for headed local runs, so a watched test is not left in a
+ * small default window. It is skipped when the window size is already decided elsewhere:
+ * headless runs and containers (explicit 1920x1080), or the user's own browser arguments.
+ */
+final class WindowSizing {
+
+    private WindowSizing() {}
+
+    static boolean shouldMaximize(boolean headless, boolean container, List<String> userArguments) {
+        if (headless || container) {
+            return false;
+        }
+        if (userArguments != null) {
+            for (String arg : userArguments) {
+                String a = arg == null ? "" : arg.toLowerCase();
+                if (a.startsWith("--start-maximized") || a.startsWith("--start-fullscreen")
+                        || a.startsWith("--kiosk") || a.startsWith("-kiosk")
+                        || a.startsWith("--window-size") || a.startsWith("--width")
+                        || a.startsWith("--height") || a.startsWith("-width")
+                        || a.startsWith("-height")) {
+                    return false;
+                }
+            }
+        }
+        return true;
+    }
+}

src/test/java/com/seleniumboot/unit/WindowSizingTest.java

@@ -0,0 +1,34 @@
+package com.seleniumboot.unit;
+
+import org.testng.annotations.Test;
+
+import java.lang.reflect.Method;
+import java.util.List;
+
+import static org.testng.Assert.assertEquals;
+
+public class WindowSizingTest {
+
+    private static boolean maximize(boolean headless, boolean container, List<String> args) throws Exception {
+        Class<?> c = Class.forName("com.seleniumboot.driver.WindowSizing");
+        Method m = c.getDeclaredMethod("shouldMaximize", boolean.class, boolean.class, List.class);
+        m.setAccessible(true);
+        return (boolean) m.invoke(null, headless, container, args);
+    }
+
+    @Test public void headedLocalMaximizesByDefault() throws Exception {
+        assertEquals(maximize(false, false, null), true);
+        assertEquals(maximize(false, false, List.of("--disable-notifications")), true);
+    }
+
+    @Test public void headlessAndContainerDoNot() throws Exception {
+        assertEquals(maximize(true, false, null), false);
+        assertEquals(maximize(false, true, null), false);
+    }
+
+    @Test public void userSizingArgumentsWin() throws Exception {
+        for (String a : List.of("--start-maximized", "--window-size=800,600", "--kiosk", "--width=900", "-height=700")) {
+            assertEquals(maximize(false, false, List.of(a)), false, a);
+        }
+    }
+}