Redesign MockMvcHtmlUnitDriverBuilder API

This commit introduces a dedicated build() method in
MockMvcHtmlUnitDriverBuilder to replace createDriver(). In addition,
the configureDriver() method has been renamed to withDelegate() and now
returns the builder for further customization.

This commit also overhauls the Javadoc for static factory methods and
the class-level Javadoc in MockMvcHtmlUnitDriverBuilder for greater
clarity to end users.

Issues SPR-13158

spring-test/src/main/java/org/springframework/test/web/servlet/htmlunit/MockMvcWebClientBuilder.java

@@ -85,7 +85,7 @@ public class MockMvcWebClientBuilder extends MockMvcWebConnectionBuilderSupport<
 	 * {@link WebApplicationContext} and {@link MockMvcConfigurer}.
 	 * @param context the {@code WebApplicationContext} to create a {@link MockMvc}
 	 * instance from; never {@code null}
-	 * @param configurer the MockMvcConfigurer to apply; never {@code null}
+	 * @param configurer the {@code MockMvcConfigurer} to apply; never {@code null}
 	 * @return the MockMvcWebClientBuilder to customize
 	 */
 	public static MockMvcWebClientBuilder webAppContextSetup(WebApplicationContext context, MockMvcConfigurer configurer) {

spring-test/src/main/java/org/springframework/test/web/servlet/htmlunit/webdriver/MockMvcHtmlUnitDriverBuilder.java

@@ -20,16 +20,18 @@ import org.openqa.selenium.htmlunit.HtmlUnitDriver;
 
 import org.springframework.test.web.servlet.MockMvc;
 import org.springframework.test.web.servlet.htmlunit.MockMvcWebConnectionBuilderSupport;
+import org.springframework.test.web.servlet.htmlunit.WebRequestMatcher;
 import org.springframework.test.web.servlet.setup.MockMvcConfigurer;
+import org.springframework.util.Assert;
 import org.springframework.web.context.WebApplicationContext;
 
 import com.gargoylesoftware.htmlunit.BrowserVersion;
 import com.gargoylesoftware.htmlunit.WebClient;
 
 /**
- * Convenience class for building an {@link HtmlUnitDriver} that delegates
- * to {@link MockMvc} and optionally delegates to an actual connection for
- * specific requests.
+ * {@code MockMvcHtmlUnitDriverBuilder} simplifies the building of an
+ * {@link HtmlUnitDriver} that delegates to {@link MockMvc} and optionally
+ * delegates to an actual connection for specific requests.
  *
  * <p>By default, the driver will delegate to {@code MockMvc} to handle
  * requests to {@code localhost} and to a {@link WebClient} to handle any
@@ -38,9 +40,17 @@ import com.gargoylesoftware.htmlunit.WebClient;
  * @author Rob Winch
  * @author Sam Brannen
  * @since 4.2
+ * @see #mockMvcSetup(MockMvc)
+ * @see #webAppContextSetup(WebApplicationContext)
+ * @see #webAppContextSetup(WebApplicationContext, MockMvcConfigurer)
+ * @see #javascriptEnabled(boolean)
+ * @see #withDelegate(WebConnectionHtmlUnitDriver)
+ * @see #build()
  */
 public class MockMvcHtmlUnitDriverBuilder extends MockMvcWebConnectionBuilderSupport<MockMvcHtmlUnitDriverBuilder> {
 
+	private HtmlUnitDriver driver;
+
 	private boolean javascriptEnabled = true;
 
 
@@ -57,41 +67,49 @@ public class MockMvcHtmlUnitDriverBuilder extends MockMvcWebConnectionBuilderSup
 	}
 
 	/**
-	 * Create a new instance using the supplied {@link WebApplicationContext}.
-	 * @param context the WebApplicationContext to use; never {@code null}
+	 * Create a new {@code MockMvcHtmlUnitDriverBuilder} based on the supplied
+	 * {@link MockMvc} instance.
+	 * @param mockMvc the {@code MockMvc} instance to use; never {@code null}
 	 * @return the MockMvcHtmlUnitDriverBuilder to customize
 	 */
-	public static MockMvcHtmlUnitDriverBuilder webAppContextSetup(WebApplicationContext context) {
-		return new MockMvcHtmlUnitDriverBuilder(context);
+	public static MockMvcHtmlUnitDriverBuilder mockMvcSetup(MockMvc mockMvc) {
+		Assert.notNull(mockMvc, "MockMvc must not be null");
+		return new MockMvcHtmlUnitDriverBuilder(mockMvc);
 	}
 
 	/**
-	 * Create a new instance using the supplied {@link WebApplicationContext}
-	 * and {@link MockMvcConfigurer}.
-	 * @param context the WebApplicationContext to create a MockMvc instance from;
-	 * never {@code null}
-	 * @param configurer the MockMvcConfigurer to apply; never {@code null}
+	 * Create a new {@code MockMvcHtmlUnitDriverBuilder} based on the supplied
+	 * {@link WebApplicationContext}.
+	 * @param context the {@code WebApplicationContext} to create a {@link MockMvc}
+	 * instance from; never {@code null}
 	 * @return the MockMvcHtmlUnitDriverBuilder to customize
 	 */
-	public static MockMvcHtmlUnitDriverBuilder webAppContextSetup(WebApplicationContext context,
-			MockMvcConfigurer configurer) {
-		return new MockMvcHtmlUnitDriverBuilder(context, configurer);
+	public static MockMvcHtmlUnitDriverBuilder webAppContextSetup(WebApplicationContext context) {
+		Assert.notNull(context, "WebApplicationContext must not be null");
+		return new MockMvcHtmlUnitDriverBuilder(context);
 	}
 
 	/**
-	 * Create a new instance using the supplied {@link MockMvc} instance.
-	 * @param mockMvc the MockMvc instance to use; never {@code null}
+	 * Create a new {@code MockMvcHtmlUnitDriverBuilder} based on the supplied
+	 * {@link WebApplicationContext} and {@link MockMvcConfigurer}.
+	 * @param context the {@code WebApplicationContext} to create a {@link MockMvc}
+	 * instance from; never {@code null}
+	 * @param configurer the {@code MockMvcConfigurer} to apply; never {@code null}
 	 * @return the MockMvcHtmlUnitDriverBuilder to customize
 	 */
-	public static MockMvcHtmlUnitDriverBuilder mockMvcSetup(MockMvc mockMvc) {
-		return new MockMvcHtmlUnitDriverBuilder(mockMvc);
+	public static MockMvcHtmlUnitDriverBuilder webAppContextSetup(WebApplicationContext context,
+			MockMvcConfigurer configurer) {
+		Assert.notNull(context, "WebApplicationContext must not be null");
+		Assert.notNull(configurer, "MockMvcConfigurer must not be null");
+		return new MockMvcHtmlUnitDriverBuilder(context, configurer);
 	}
 
 	/**
 	 * Specify whether JavaScript should be enabled.
 	 * <p>Default is {@code true}.
-	 * @param javascriptEnabled if JavaScript should be enabled or not.
-	 * @return the builder for further customizations
+	 * @param javascriptEnabled {@code true} if JavaScript should be enabled
+	 * @return this builder for further customizations
+	 * @see #build()
 	 */
 	public MockMvcHtmlUnitDriverBuilder javascriptEnabled(boolean javascriptEnabled) {
 		this.javascriptEnabled = javascriptEnabled;
@@ -99,25 +117,37 @@ public class MockMvcHtmlUnitDriverBuilder extends MockMvcWebConnectionBuilderSup
 	}
 
 	/**
-	 * Create a new {@link HtmlUnitDriver} with the {@link BrowserVersion}
-	 * set to {@link BrowserVersion#CHROME CHROME}.
-	 * <p>For additional configuration options, use {@link #configureDriver}.
-	 * @return the {@code HtmlUnitDriver} to use
-	 * @see #configureDriver(WebConnectionHtmlUnitDriver)
+	 * Supply the {@code WebConnectionHtmlUnitDriver} that the driver
+	 * {@linkplain #build built} by this builder should delegate to when
+	 * processing non-{@linkplain WebRequestMatcher matching} requests.
+	 * @param driver the {@code WebConnectionHtmlUnitDriver} to delegate to
+	 * for requests that do not match; never {@code null}
+	 * @return this builder for further customizations
+	 * @see #build()
 	 */
-	public HtmlUnitDriver createDriver() {
-		return configureDriver(new WebConnectionHtmlUnitDriver(BrowserVersion.CHROME));
+	public MockMvcHtmlUnitDriverBuilder withDelegate(WebConnectionHtmlUnitDriver driver) {
+		Assert.notNull(driver, "driver must not be null");
+		driver.setJavascriptEnabled(this.javascriptEnabled);
+		driver.setWebConnection(createConnection(driver.getWebConnection()));
+		this.driver = driver;
+		return this;
 	}
 
 	/**
-	 * Configure an existing {@link WebConnectionHtmlUnitDriver}.
-	 * @param driver the WebConnectionHtmlUnitDriver to configure
+	 * Build the {@link HtmlUnitDriver} configured via this builder.
+	 * <p>The returned driver will use the configured {@link MockMvc} instance
+	 * for processing any {@linkplain WebRequestMatcher matching} requests
+	 * and a delegate {@code HtmlUnitDriver} for all other requests.
+	 * <p>If a {@linkplain #withDelegate delegate} has been explicitly configured,
+	 * it will be used; otherwise, a default {@code WebConnectionHtmlUnitDriver}
+	 * with the {@link BrowserVersion} set to {@link BrowserVersion#CHROME CHROME}
+	 * will be configured as the delegate.
 	 * @return the {@code HtmlUnitDriver} to use
+	 * @see #withDelegate(WebConnectionHtmlUnitDriver)
 	 */
-	public HtmlUnitDriver configureDriver(WebConnectionHtmlUnitDriver driver) {
-		driver.setJavascriptEnabled(javascriptEnabled);
-		driver.setWebConnection(createConnection(driver.getWebConnection()));
-		return driver;
+	public HtmlUnitDriver build() {
+		return (this.driver != null ? this.driver
+				: withDelegate(new WebConnectionHtmlUnitDriver(BrowserVersion.CHROME)).build());
 	}
 
-}
+}

spring-test/src/test/java/org/springframework/test/web/servlet/htmlunit/webdriver/MockMvcHtmlUnitDriverBuilderTests.java

@@ -42,6 +42,7 @@ import org.springframework.web.servlet.config.annotation.EnableWebMvc;
 
 import static org.hamcrest.CoreMatchers.*;
 import static org.junit.Assert.*;
+import static org.springframework.test.web.servlet.htmlunit.webdriver.MockMvcHtmlUnitDriverBuilder.*;
 
 /**
  * Integration tests for {@link MockMvcHtmlUnitDriverBuilder}.
@@ -70,54 +71,42 @@ public class MockMvcHtmlUnitDriverBuilderTests {
 	}
 
 	@Test(expected = IllegalArgumentException.class)
-	public void mockMvcSetupNull() {
-		MockMvcHtmlUnitDriverBuilder.mockMvcSetup(null);
+	public void webAppContextSetupNull() {
+		webAppContextSetup(null);
 	}
 
 	@Test(expected = IllegalArgumentException.class)
-	public void webAppContextSetupNull() {
-		MockMvcHtmlUnitDriverBuilder.webAppContextSetup(null);
+	public void mockMvcSetupNull() {
+		mockMvcSetup(null);
 	}
 
 	@Test
-	public void mockMvcSetupAndConfigureDriver() throws Exception {
-		Assume.group(TestGroup.PERFORMANCE);
-
-		this.driver = MockMvcHtmlUnitDriverBuilder
-				.mockMvcSetup(this.mockMvc)
-				.configureDriver(new WebConnectionHtmlUnitDriver());
+	public void mockMvcSetupWithCustomDriverDelegate() throws Exception {
+		WebConnectionHtmlUnitDriver preconfiguredDriver = new WebConnectionHtmlUnitDriver();
+		this.driver = mockMvcSetup(this.mockMvc).withDelegate(preconfiguredDriver).build();
 
 		assertMvcProcessed("http://localhost/test");
-		assertDelegateProcessed("http://example.com/");
+		Assume.group(TestGroup.PERFORMANCE, () -> assertDelegateProcessed("http://example.com/"));
 	}
 
 	@Test
-	public void mockMvcSetupAndCreateDriver() throws Exception {
-		Assume.group(TestGroup.PERFORMANCE);
-
-		this.driver = MockMvcHtmlUnitDriverBuilder
-				.mockMvcSetup(this.mockMvc)
-				.createDriver();
+	public void mockMvcSetupWithDefaultDriverDelegate() throws Exception {
+		this.driver = mockMvcSetup(this.mockMvc).build();
 
 		assertMvcProcessed("http://localhost/test");
-		assertDelegateProcessed("http://example.com/");
+		Assume.group(TestGroup.PERFORMANCE, () -> assertDelegateProcessed("http://example.com/"));
 	}
 
 	@Test
 	public void javaScriptEnabledByDefault() {
-		this.driver = MockMvcHtmlUnitDriverBuilder
-				.mockMvcSetup(this.mockMvc)
-				.createDriver();
+		this.driver = mockMvcSetup(this.mockMvc).build();
 
 		assertTrue(this.driver.isJavascriptEnabled());
 	}
 
 	@Test
 	public void javaScriptDisabled() {
-		this.driver = MockMvcHtmlUnitDriverBuilder
-				.mockMvcSetup(this.mockMvc)
-				.javascriptEnabled(false)
-				.createDriver();
+		this.driver = mockMvcSetup(this.mockMvc).javascriptEnabled(false).build();
 
 		assertFalse(this.driver.isJavascriptEnabled());
 	}

src/asciidoc/testing.adoc

@@ -4594,7 +4594,7 @@ WebDriver driver;
 public void setup() {
 	driver = MockMvcHtmlUnitDriverBuilder
 		.webAppContextSetup(context)
-		.createDriver();
+		.build();
 }
 ----
 
@@ -4818,7 +4818,7 @@ following:
 def setup() {
 	browser.driver = MockMvcHtmlUnitDriverBuilder
 		.webAppContextSetup(context, springSecurity())
-		.createDriver()
+		.build()
 }
 ----