JarCasting
adamant-driver
AdamantDriver is a library combining Selenium WebDriver + TestNG. It enables a user to begin writing tests very quickly with very little boiler-plate code.
The first 3 links will get you started. Links 4-10 are advanced usage.
- Add the adamant-driver jar to your project
- Inject a WebDriver object as a test parameter
- Add AdamantListener to testng.xml
- Using a DataProvider
- AdamantDriver Parameters
- The DriverCapabilities Interface
- The DriverOptions Interface
- The DriverProxy Interface
- Injecting a BrowserMobProxy object as a test parameter
- Taking Screenshots
- Manually building the project
- Limitations
- TODO Features
- Help
1. Add the adamant-driver jar to your project
This library is now hosted at Maven Central. SNAPSHOT versions are hosted at https://oss.sonatype.org.
The latest version is 1.1.0-beta-1:
<dependency>
<groupId>com.github.ryanlevell</groupId>
<artifactId>adamant-driver</artifactId>
<version>1.1.0-beta-1</version>
</dependency>
2. Inject a WebDriver object as a test parameter
@Test
public void test(WebDriver driver) {
// the driver is initialized and ready to use
driver.get("http://google.com");
Assert.assertEquals(driver.getTitle(), "Google");
// the driver is closed automatically at the end of a test
}
3. Add AdamantListener to testng.xml
<suite name="SomeSuite">
<listeners>
<listener class-name="com.github.ryanlevell.adamantdriver.AdamantListener" />
</listeners>
...
</suite>
Execute tests:
mvn test
4. Using a DataProvider
A data provider is optional for Selenium tests. They can be used normally and the driver will still be injected. The driver must be the first parameter followed by the data provider parameters:
@Test(dataProvider="someDataProvider")
public void test(WebDriver driver, String url, String title) {
driver.get(url);
Assert.assertEquals(driver.getTitle(), title);
}
@DataProvider(name="someDataProvider")
public static Object[][] dataProvider() {
return new Object[][]{ {"http://google.com", "Google"} };
}
5. AdamantDriver Parameters
No AdamantDriver parameters are required, but they can be used for additional functionality.
All AdamantDriver specific parameters can be specified in 2 ways:
1. testng.xml parameter:
...
<suite name="suite-name">
<parameter name="parameter_name" value="parameter_value" />
...
</suite>
...
2. command line parameter:
mvn test -Dparameter_name=parameter_value
Parameters:
| parameter | values | default | description |
|---|---|---|---|
| browser | firefox, chrome | firefox | The driver to use for testing. |
| chrome_path | <full path to chrome driver> | none | The path to the chrome driver. |
| capabilities_class | <fully qualified class> | none | A class that implements the DriverCapabilities interface. |
| options_class | <fully qualified class> | none | A class that implements the DriverOptions interface. |
| proxy_class | <fully qualified class> | none | A class that implements the DriverProxy interface. |
| use_grid | true, false | false | Whether to run tests locally or on the grid. |
| grid_url | <your grid URL> | none | The URL to the Selenium grid hub. |
| take_screenshot | all, pass, fail, skip, fail_within_success_percentage, none | none | When to take screenshots. |
| screenshot_path | <relative path to a screenshot folder> | screenshots | The folder is save screenshots to. |
6. The DriverCapabilities Interface
The DriverCapabilities interface provides a way to supply custom DesiredCapabilities to the WebDriver object before the test if the capabilities_class parameter is set.
public class MyCapabilities implements DriverCapabilities {
public void getCapabilities(Browser browser, DesiredCapabilities caps) {
caps.setCapability(CapabilityType.UNEXPECTED_ALERT_BEHAVIOUR, "accept");
}
}
7. The DriverOptions Interface
The DriverOptions interface provides a way to supply custom Options to the WebDriver object before the test if the options_class parameter is set.
public class MyOptions implements DriverOptions {
public void getOptions(Browser browser, Options options) {
options.window().maximize();
}
}
8. The DriverProxy Interface
The DriverProxy interface provides a way to supply custom BrowserMobProxy settings before a test if the proxy_class parameter is set and Injecting a BrowserMobProxy object as a test parameter is injected. Note, if you manually set a proxy in DesiredCapabilities this will NOT be used and if the injected BrowserMobProxy is present, it will override the initial proxy.
public class MyProxy implements DriverProxy {
public void getProxy(BrowserMobProxy proxy) {
proxy.addResponseFilter(new ResponseFilter() {
public void filterResponse(HttpResponse response, HttpMessageContents contents, HttpMessageInfo messageInfo) {
contents.setTextContents("Edit the response before testing");
}
});
}
}
9. Injecting a BrowserMobProxy object as a test parameter
In addition to injecting a WebDriver object, a BrowserMobProxy object can also be injected. The proxy object must be the second parameter and the first parameter must be a WebDriver object. As usual, a DataProvider can still be used with the same rule as when injecting a WebDriver object: the DataProvider parameters must follow the WebDriver and BrowserMobProxy parameters. The proxy can be customized before a test by implementing The DriverProxy Interface.
@Test
public void test(WebDriver driver, BrowserMobProxy proxy) {
proxy.newHar();
driver.get("https://google.com");
List<HarEntry> harEntries = proxy.getHar().getLog().getEntries();
Assert.assertTrue(!harEntries.isEmpty(), "Har was empty");
}
10. Taking Screenshots
Screenshots can be taken using the take_screenshot parameter and optionally the screenshot_path parameter.
When ran with maven screenshots will default to the folder target/screenshots, unless screenshot_path is specified.
Screenshot naming convention is timestamp_testName_testNumber.
The testName will either be the test name such as @Test(testName=... or the test method name if @Test(testName=... is not used.
The testNumber is a unique, incremented number that AdamantDriver gives to all tests.
take_screenshot value |
Description |
|---|---|
| all | Take a screenshot after every test. |
| pass | Take a screenshot after a test successfully passes. |
| fail | Take a screenshot after a test fails. |
| skip | Take a screenshot after a test is skipped. |
| pass_within_success_percentage | Take a screenshot after a test fails, but within the success percentage. |
| none | Never take a screenshot. This is the default value. |
11. Manually building the project
git clone https://github.com/ryanlevell/adamant-driver.git
cd adamant-driver
mvn package -Dmaven.test.skip=true -Dorg.slf4j.simpleLogger.defaultLogLevel=debug
The jar can be found in <project root>/target/adamant-driver...jar-with-dependencies.jar.
12. Limitations
- The TestNG
@Parameterannotation cannot be used with a WebDriver test. This is because AdamantDriver injects a data provider to all WebDriver tests. - Only
FirefoxDriverandChromeDrivercan be used. More browsers will be added. - Anything not supported described in TODO Features.
13. TODO Features
- Screenshots + path/folder
- Retry analyzer + boolean whether to remove retries from results
14. Help
How do I use SNAPSHOT versions?
SNAPSHOT versions can be used by adding the following to settings.xml or pom.xml:
<repository>
<id>snapshots-repo</id>
<url>https://oss.sonatype.org/content/repositories/snapshots</url>
<releases><enabled>false</enabled></releases>
<snapshots><enabled>true</enabled></snapshots>
</repository>
Can @Listener(AdamantListener) be used instead of the <listener> tag?
No, AdamantListener implements IAnnotationTransformer. The TestNG documentation states:
The @Listeners annotation can contain any class that extends org.testng.ITestNGListener except IAnnotationTransformer and IAnnotationTransformer2. The reason is that these listeners need to be known very early in the process so that TestNG can use them to rewrite your annotations, therefore you need to specify these listeners in your testng.xml file.
Tip To Eclipse Users:
If you are running tests via the Eclipse TestNG plugin, you may need to point Eclipse to your testng.xml. The TestNG plugin uses its own testng.xml by default. Follow the steps below to use your own XML as the template:
Project>Properties- Click
TestNGin the left panel - Find
Template XML file - Enter the path to your XML, or browse for it
- Click
Apply