Skip to content

Commit

Permalink
Convert Docs for Webdriver Containers (#2927)
Browse files Browse the repository at this point in the history 
Co-authored-by: Richard North <rich.north@gmail.com>
  • Loading branch information
@raynigon @rnorth
raynigon and rnorth committed Jun 29, 2020
1 parent 1ad7ffa commit b0dbd31
Show file tree
Hide file tree
Showing 5 changed files with 86 additions and 57 deletions.
62 changes: 23 additions & 39 deletions docs/modules/webdriver_containers.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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`.

Expand Down
73 changes: 55 additions & 18 deletions ...elenium/src/test/java/org/testcontainers/junit/ChromeRecordingWebDriverContainerTest.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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 {
Expand All @@ -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();
Expand All @@ -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 { }
}
}
2 changes: 2 additions & 0 deletions modules/selenium/src/test/java/org/testcontainers/junit/ChromeWebDriverContainerTest.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,9 +11,11 @@
*/
public class ChromeWebDriverContainerTest extends BaseWebDriverContainerTest {

// junitRule {
@Rule
public BrowserWebDriverContainer chrome = new BrowserWebDriverContainer()
.withCapabilities(new ChromeOptions());
// }

@Before
public void checkBrowserIsIndeedChrome() {
Expand Down
2 changes: 2 additions & 0 deletions modules/selenium/src/test/java/org/testcontainers/junit/FirefoxWebDriverContainerTest.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,9 +11,11 @@
*/
public class FirefoxWebDriverContainerTest extends BaseWebDriverContainerTest {

// junitRule {
@Rule
public BrowserWebDriverContainer firefox = new BrowserWebDriverContainer()
.withCapabilities(new FirefoxOptions());
// }

@Before
public void checkBrowserIsIndeedFirefox() {
Expand Down
4 changes: 4 additions & 0 deletions ...es/selenium/src/test/java/org/testcontainers/junit/LocalServerWebDriverContainerTest.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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();

Expand Down

0 comments on commit b0dbd31

Please sign in to comment.