Getting started

This article explains how to set up Sahagin-Java. If you want to set up Sahagin-Groovy, see here.

1. sahagin.jar dependency and JVM argument setting

If you use Maven

Add dependency and test execution JVM argumment to your pom.xml file.

  <properties>
    <!-- use the current latest version --> 
    <sahagin.version>0.10.1</sahagin.version>
  </properties>
  ...
  <dependencies>
    <dependency>
      <groupId>org.sahagin</groupId>  
       <artifactId>sahagin</artifactId>  
       <version>${sahagin.version}</version> 
    </dependency>
  </dependencies>
  ...
  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-surefire-plugin</artifactId>
        <version>2.18(or any other version)</version>
        <configuration>
          <argLine>
            -javaagent:${settings.localRepository}/org/sahagin/sahagin/${sahagin.version}/sahagin-${sahagin.version}.jar
          </argLine>
        </configuration>
      </plugin>
    </plugins>
  </build>

If you use Gradle

Add dependency and test execution JVM argumment to your build.gradle file.

// use the current latest version
def sahaginVersion = '0.10.1'

...

dependencies {
    compile 'org.sahagin:sahagin:' + sahaginVersion
}

...

test {
    doFirst {
        // search sahagin jar file in the local cache
        def sahaginJar = project.configurations.testCompile.find {
            it.name == 'sahagin-' + sahaginVersion + '.jar'
        }
        jvmArgs '-javaagent:' + sahaginJar
    }
}

If you use jar file directly

Download sahagin-0.10.1.zip from here and add all jar files in the zip file to the Java class path.

You must add JVM argument -javaagent:<path to sahagin.jar> when you run JUnit tests.

2. Add annotations

Add @PageDoc annotations to your page object class declarations, and add @TestDoc annotations to your page object methods or any other methods.

import org.sahagin.runlib.external.PageDoc;
import org.sahagin.runlib.external.TestDoc;

@PageDoc("Contact page")
public class ContactPage {
    
    @TestDoc("set name '{name}'")
    public void setName(String name) {
        ....
    }
    
    @TestDoc("name")
    public String getName() {
        ....
    }

    @TestDoc("set mail address '{0}'")
    public void setMail(String email) {
        ....
    }

    ....
}

• Methods or classes without the annotations are also displayed on the Sahagin report, so you don't need to add the annotations to all your classes and methods.
• Use {parameter name} or {parameter index start from 0} to include method argument information in @TestDoc
• @TestDoc description of the get methods such as "getName" method should be noun such as "name" rather than verb such as "get name". Then, assertEquals(contactPage.getName(), 'user A') becomes "check that name equals to 'user A'", for example.

3. Screen capture set up

To take screen captures, call WebDriverAdapter.setAdapter method with WebDriver instance used in each test at JUnit @Before method or other test set up method.

import org.sahagin.runlib.external.adapter.webdriver.WebDriverAdapter;

public class SampleTest {

  @Before
  public void setUp() {
      wd = new FirefoxDriver();
      WebDriverAdapter.setAdapter(wd);
      ...
  }
}

If you use FluentLenium, use FluentLeniumAdapter.

import org.sahagin.runlib.external.adapter.fluentlenium.FluentLeniumAdapter;

public class SampleTest extends FluentTest {

  @Before
  public void setUp() {
      FluentLeniumAdapter.setAdapter(this);
      ...
  }
}

If you use Appium, use AppiumAdapter. You can also use SelendroidAdapter and IOSDriverAdapter.

import org.sahagin.runlib.external.adapter.appium.AppiumAdapter;

public class SampleTest {

  @Before
  public void setUp() {
      wd = new AndroidDriver(...);
      AppiumAdapter.setAdapter(wd);
      ...
  }
}

4. Create configuration file sahagin.yml

Create a file "sahagin.yml" on the Java project root directory.

Then change the "testDir" value to the directory your test files are located.

# Sahagin configuration file written by YAML style.

java:
  # Root directory of test Java files
  # (absolute path or relative path from this YAML file).
  # All test methods and methods annotated by @TestDoc 
  # must be located under this directory.
  testDir: src/test/java

5. Run test and generate report

Run your JUnit tests.

If you use Maven

Run "mvn test" with your pom.xml.

Note that Maven executes only tests whose file names are "Test*.java" or "*Test.java" or "*TestCase.java" by default.

If you use Gradle

Run "gradle test" with your build.gradle.

If you use jar file directly

Run test with the javaagent argument.

Test result report

The HTML report sahagin-rerpot/index.html is generated on the sahagin.yml directory after the test run.

6. Set up Jenkins plug-in

Jenkins Sahagin plug-in displays HTML report generated by Sahagin on Jenkins.

First, go to Manage Jenkins > Manage Plugins > Available and find Sahagin Plugin and install it. Then restart Jenkins.

Then, go to the project configuration page, select Post-build Action Publish Sahagin HTML report, and specify the path to sahagin.yml.

Then, execute JUnit test on Jenkins with pom.xml or build.gradle created above, and the link to the Sahagin report list will be added to the Jenkins build result page.

Note that the report is not generated only with Jenkins plug-in, you need the all set up steps from "1. sahagin.jar dependency and JVM argument setting" to "5. Run test and generate report". Also note that the version number of sahagin.jar and Jenkins Sahagin plug-in should be the same.

If you use Publish JUnit test result report as Post-build Action, add Additional test report feature Add Sahagin test report link to each test result.

After running your tests, the link to the Sahagin report is added to the JUnit each test result page.

Next step

If you want to know more about Sahagin features, go to Various features.