Convert Docs for Webdriver Containers (#2927)

raynigon · rnorth · web-flow · commit b0dbd3190e20 · 2020-06-29T22:02:21.000+01:00
Co-authored-by: Richard North &lt;rich.north@gmail.com&gt;
diff --git a/docs/modules/webdriver_containers.md b/docs/modules/webdriver_containers.md
@@ -22,70 +22,54 @@ every test.
 ## Example
 
 The following field in your JUnit UI test class will prepare a container running Chrome:
-```java
-@Rule
-public BrowserWebDriverContainer chrome =
-    new BrowserWebDriverContainer()
-            .withCapabilities(new ChromeOptions());
-```
+<!--codeinclude-->
+[Chrome](../../modules/selenium/src/test/java/org/testcontainers/junit/ChromeWebDriverContainerTest.java) inside_block:junitRule
+<!--/codeinclude-->
+
         
 Now, instead of instantiating an instance of WebDriver directly, use the following to obtain an instance inside your
 test methods:
-```java
-RemoteWebDriver driver = chrome.getWebDriver();
-```
+<!--codeinclude-->
+[RemoteWebDriver](../../modules/selenium/src/test/java/org/testcontainers/junit/LocalServerWebDriverContainerTest.java) inside_block:getWebDriver
+<!--/codeinclude-->
 
 You can then use this driver instance like a regular WebDriver.
 
 Note that, if you want to test a **web application running on the host machine** (the machine the JUnit tests are
 running on - which is quite likely), you'll need to replace any references to `localhost` with an IP address that the
 Docker container can reach. Use the `getTestHostIpAddress()` method, e.g.:
-```java
-driver.get("http://" + chrome.getTestHostIpAddress() + ":8080/");
-```
+<!--codeinclude-->
+[Open Web Page](../../modules/selenium/src/test/java/org/testcontainers/junit/LocalServerWebDriverContainerTest.java) inside_block:getPage
+<!--/codeinclude-->
+
 
 ## Options
 
 ### Other browsers
 
 At the moment, Chrome and Firefox are supported. To switch, simply change the first parameter to the rule constructor:
-```java
-new BrowserWebDriverContainer()
-        .withCapabilities(new ChromeOptions());
-```
-        
-or
-```java
-new BrowserWebDriverContainer()
-        .withCapabilities(new FirefoxOptions());
-```
+<!--codeinclude-->
+[Chrome](../../modules/selenium/src/test/java/org/testcontainers/junit/ChromeWebDriverContainerTest.java) inside_block:junitRule
+[Firefox](../../modules/selenium/src/test/java/org/testcontainers/junit/FirefoxWebDriverContainerTest.java) inside_block:junitRule
+<!--/codeinclude-->
 
 ### Recording videos
 
 By default, no videos will be recorded. However, you can instruct Testcontainers to capture videos for all tests or
 just for failing tests.
 
-To do this, simply add extra parameters to the rule constructor:
-```java
-new BrowserWebDriverContainer()
-        .withCapabilities(new ChromeOptions())
-        .withRecordingMode(VncRecordingMode.RECORD_ALL, new File("./target/"))
-```
+<!--codeinclude-->
+[Record all Tests](../../modules/selenium/src/test/java/org/testcontainers/junit/ChromeRecordingWebDriverContainerTest.java) inside_block:recordAll
+[Record failing Tests](../../modules/selenium/src/test/java/org/testcontainers/junit/ChromeRecordingWebDriverContainerTest.java) inside_block:recordFailing
+<!--/codeinclude-->
 
-or if you only want videos for test failures:
-```java
-new BrowserWebDriverContainer()
-        .withCapabilities(new ChromeOptions())
-        .withRecordingMode(VncRecordingMode.RECORD_FAILING, new File("./target/"))
-```
 Note that the seconds parameter to `withRecordingMode` should be a directory where recordings can be saved.
 
 If you would like to customise the file name of the recording, or provide a different directory at runtime based on the description of the test and/or its success or failure, you may provide a custom recording file factory as follows:
-```java
-new BrowserWebDriverContainer()
-        //...
-        .withRecordingFileFactory(new CustomRecordingFileFactory())
-```
+<!--codeinclude-->
+[CustomRecordingFileFactory](../../modules/selenium/src/test/java/org/testcontainers/junit/ChromeRecordingWebDriverContainerTest.java) inside_block:withRecordingFileFactory
+<!--/codeinclude-->
+
 
 Note the factory must implement `org.testcontainers.containers.RecordingFileFactory`.
 
diff --git a/modules/selenium/src/test/java/org/testcontainers/junit/ChromeRecordingWebDriverContainerTest.java b/modules/selenium/src/test/java/org/testcontainers/junit/ChromeRecordingWebDriverContainerTest.java
@@ -12,9 +12,12 @@
 import org.testcontainers.containers.DefaultRecordingFileFactory;
 import org.testcontainers.lifecycle.TestDescription;
 
+import java.io.File;
 import java.util.Optional;
-import static org.junit.Assert.assertTrue;
+
+import static org.junit.Assert.assertEquals;
 import static org.testcontainers.containers.BrowserWebDriverContainer.VncRecordingMode.RECORD_ALL;
+import static org.testcontainers.containers.BrowserWebDriverContainer.VncRecordingMode.RECORD_FAILING;
 
 @RunWith(Enclosed.class)
 public class ChromeRecordingWebDriverContainerTest extends BaseWebDriverContainerTest {
@@ -26,10 +29,14 @@ public static class ChromeThatRecordsAllTests {
 
         @Test
         public void recordingTestThatShouldBeRecordedAndRetained() {
+            File target = vncRecordingDirectory.getRoot();
             try (
+                // recordAll {
+                // To do this, simply add extra parameters to the rule constructor:
                 BrowserWebDriverContainer chrome = new BrowserWebDriverContainer()
                     .withCapabilities(new ChromeOptions())
-                    .withRecordingMode(RECORD_ALL, vncRecordingDirectory.getRoot())
+                    .withRecordingMode(RECORD_ALL, target)
+                    // }
                     .withRecordingFileFactory(new DefaultRecordingFileFactory())
             ) {
                 chrome.start();
@@ -48,36 +55,66 @@ public String getFilesystemFriendlyName() {
                 }, Optional.empty());
 
                 String[] files = vncRecordingDirectory.getRoot().list(new PatternFilenameFilter("PASSED-.*\\.flv"));
-                assertTrue("Recorded file not found", files.length == 1);
+                assertEquals("Recorded file not found", 1, files.length);
             }
         }
     }
 
     public static class ChromeThatRecordsFailingTests {
 
         @Rule
-        public BrowserWebDriverContainer chrome = new BrowserWebDriverContainer()
-                .withCapabilities(new ChromeOptions());
+        public TemporaryFolder vncRecordingDirectory = new TemporaryFolder();
 
         @Test
         public void recordingTestThatShouldBeRecordedButNotPersisted() {
-            doSimpleExplore(chrome);
+            try (
+                // withRecordingFileFactory {
+                BrowserWebDriverContainer chrome = new BrowserWebDriverContainer()
+                    // }
+                    .withCapabilities(new ChromeOptions())
+                    // withRecordingFileFactory {
+                    .withRecordingFileFactory(new CustomRecordingFileFactory())
+                // }
+            ) {
+                chrome.start();
+
+                doSimpleExplore(chrome);
+            }
         }
 
         @Test
         public void recordingTestThatShouldBeRecordedAndRetained() {
-            doSimpleExplore(chrome);
-            chrome.afterTest(new TestDescription() {
-                @Override
-                public String getTestId() {
-                    return getFilesystemFriendlyName();
-                }
-
-                @Override
-                public String getFilesystemFriendlyName() {
-                    return "ChromeThatRecordsFailingTests-recordingTestThatShouldBeRecordedAndRetained";
-                }
-            }, Optional.of(new RuntimeException("Force writing of video file.")));
+            File target = vncRecordingDirectory.getRoot();
+            try (
+                // recordFailing {
+                // or if you only want videos for test failures:
+                BrowserWebDriverContainer chrome = new BrowserWebDriverContainer()
+                    .withCapabilities(new ChromeOptions())
+                    .withRecordingMode(RECORD_FAILING, target)
+                    // }
+                    .withRecordingFileFactory(new DefaultRecordingFileFactory())
+            ) {
+                chrome.start();
+
+                doSimpleExplore(chrome);
+                chrome.afterTest(new TestDescription() {
+                    @Override
+                    public String getTestId() {
+                        return getFilesystemFriendlyName();
+                    }
+
+                    @Override
+                    public String getFilesystemFriendlyName() {
+                        return "ChromeThatRecordsFailingTests-recordingTestThatShouldBeRecordedAndRetained";
+                    }
+                }, Optional.of(new RuntimeException("Force writing of video file.")));
+
+                String[] files = vncRecordingDirectory.getRoot().list(new PatternFilenameFilter("FAILED-.*\\.flv"));
+                assertEquals("Recorded file not found", 1, files.length);
+            }
+
         }
+
+        private static class CustomRecordingFileFactory extends DefaultRecordingFileFactory { }
     }
 }
diff --git a/modules/selenium/src/test/java/org/testcontainers/junit/ChromeWebDriverContainerTest.java b/modules/selenium/src/test/java/org/testcontainers/junit/ChromeWebDriverContainerTest.java
@@ -11,9 +11,11 @@
  */
 public class ChromeWebDriverContainerTest extends BaseWebDriverContainerTest {
 
+    // junitRule {
     @Rule
     public BrowserWebDriverContainer chrome = new BrowserWebDriverContainer()
         .withCapabilities(new ChromeOptions());
+    // }
 
     @Before
     public void checkBrowserIsIndeedChrome() {
diff --git a/modules/selenium/src/test/java/org/testcontainers/junit/FirefoxWebDriverContainerTest.java b/modules/selenium/src/test/java/org/testcontainers/junit/FirefoxWebDriverContainerTest.java
@@ -11,9 +11,11 @@
  */
 public class FirefoxWebDriverContainerTest extends BaseWebDriverContainerTest {
 
+    // junitRule {
     @Rule
     public BrowserWebDriverContainer firefox = new BrowserWebDriverContainer()
             .withCapabilities(new FirefoxOptions());
+    // }
 
     @Before
     public void checkBrowserIsIndeedFirefox() {
diff --git a/modules/selenium/src/test/java/org/testcontainers/junit/LocalServerWebDriverContainerTest.java b/modules/selenium/src/test/java/org/testcontainers/junit/LocalServerWebDriverContainerTest.java
@@ -49,11 +49,15 @@ public void setupLocalServer() throws Exception {
 
     @Test
     public void testConnection() {
+        // getWebDriver {
         RemoteWebDriver driver = chrome.getWebDriver();
+        // }
 
         // Construct a URL that the browser container can access
+        // getPage {
         String hostIpAddress = chrome.getTestHostIpAddress();
         driver.get("http://" + hostIpAddress + ":" + localPort);
+        // }
 
         String headingText = driver.findElement(By.cssSelector("h1")).getText().trim();
 
