Arquillian Governor Extension and the implementations which use its API give you the possibility to programmatically choose what test methods of your Arquillian tests are going to be executed and what are going to be skipped by putting your custom annotations on the test methods.
The resolution of the test method execution is done during the test class
execution in BeforeClass
phase.
Currenly, there are two implementations which use API of the Arquillian Governor extension - Arquillian JIRA Governor extension and Arquillian Skipper extension.
Arquillian Governor extension is an extension on top of which all other concrete governors are
built. When you provide some custom Governor implementation, this extension is automatically behind it.
Arquillian Governor base implementation is configured by putting the following extension definition
into arquillian.xml
like this:
<extension qualifier="governor">
</extension>
Possible properties for governor
extension:
Configuration property | Description | Default value | Possible values |
---|---|---|---|
ignore |
No test execution resolution will be done. All test methods, even annotated with |
false |
true / false |
ignoreOnly |
Fully qualified class name of |
empty string |
Fully qualified class name of an annotation you want to ignore. |
In order to use JIRA Governor extension, you have to put this dependency into your Arquillian test Maven build:
<dependency>
<groupId>org.arquillian.extension</groupId>
<artifactId>arquillian-governor-jira</artifactId>
<scope>test</scope>
</dependency>
As stated previously, JIRA Governor has the base implementation automatically bundled in it so you can configure governor
extension as well.
Arquillian JIRA Governor extension is configured by putting the following extension definition into arquillian.xml
like this:
<extension qualifier="governor-jira">
</extension>
Possible properties for governor-jira
extension:
Configuration property | Description | Default value | Possible values |
---|---|---|---|
username |
your JIRA user name. This user name will be used to log in to JIRA instance |
this property has to be set and has to be non-empty, otherwise it fails |
|
password |
your JIRA password. This password will be used to log in to JIRA instance |
this property has to be set and has to be non-empty, otherwise it fails |
|
server |
JIRA server to connect to |
any address which is valid URI and URL |
|
force |
Even JIRA status is Unresolved or Open, this test method will be executed anyway |
false |
true / false |
closePassed |
If you force the execution for some test method which has status as 'Unresolved' or 'Open' and this test succeeds and this property is set to true, JIRA issue on |
false |
true / false |
closingMessage |
Message which appears as a comment on a JIRA issue which was automatically closed. |
This JIRA issue was automatically closed by %s with Arquillian Jira Governor extension. ('%s' is replaced by username property). |
Any string. |
Due to security reasons, when you do not specify server
and username
or password
properties in arquillian.xml
for JIRA Governor, this extension looks for system properties jira.governor.server
, jira.governor.username
and
jira.governor.password
respectively.
You can set properties force
and closePassed
by system properties jira.governor.force
and jira.governor.closepassed
by setting them to "true" or "false".
Let’s have this test case:
@RunWith(Arquillian.class)
@RunAsClient
public class TestCase
{
@Test
@Jira("ARQ-1907")
public void test()
{
// this test will be run
// because ARQ-1907 is 'Done'
// so we assume that this test has to pass as well
}
@Test
@Jira("ARQ-5000")
public void test2()
{
// when this JIRA exists and its status is 'Unresolved' / 'Open'
// this test method will be skipped because you assume that
// if you run it, it would fail
}
}
If some JIRA issue is unresolved, normally, it would be skipped from
execution. However if you force it to execute by force
flag on @Jira
annotation, and this test method
passes with success, if you set property closePassed
in your arquillian.xml
, that JIRA will be
automatically marked as Done
on JIRA server.
@RunWith(Arquillian.class)
public class AutomaticClosingTestCase
{
@Test
@Jira("ARQ-5000", force = true)
public void automaticClosingTest)
{
// when this JIRA exists and its status is 'Unresolved' / 'Open'
// and you have forced its execution and you set 'closePassed'
// property in arquillian.xml to 'true',
// when this test method succeeds, it automatically resolves
// respective JIRA issue as 'Done'
}
}
In order to use Github Governor extension, you have to put this dependency into your Arquillian test Maven build:
<dependency>
<groupId>org.arquillian.extension</groupId>
<artifactId>arquillian-governor-github</artifactId>
<scope>test</scope>
</dependency>
As stated previously, Github Governor has the base implementation automatically bundled in it so you can configure governor
extension as well.
Arquillian Github Governor extension is configured by putting the following extension definition into arquillian.xml
like this:
<extension qualifier="governor-github">
</extension>
Possible properties for governor-github
extension:
Configuration property | Description | Default value | Possible values |
---|---|---|---|
username |
your Github user name. This user name will be used to log in to Github instance |
this property has to be set and has to be non-empty, otherwise it fails if no token property set |
|
password |
your Github password. This password will be used to log in to Github instance |
this property has to be set and has to be non-empty, otherwise it fails if no token property set |
|
token |
your Github personal token. This token will be used to log in to Github instance |
this property has to be set and has to be non-empty, otherwise it fails if no username and password set |
|
repositoryUser |
Username part of a Github repository |
For example in case of www.github.com/arquillian/arquillian-cube, |
|
repository |
Github repository name |
For example in case of www.github.com/arquillian/arquillian-cube, |
|
force |
Even Github status is Open, this test method will be executed anyway |
false |
true / false |
closePassed |
If you force the execution for some test method which has status as 'Open' and this test succeeds and this property is set to true, Github issue on |
false |
true / false |
closingMessage |
Message which appears as a comment on a Github issue which was automatically closed. |
This Github issue was automatically closed by %s with Arquillian Github Governor extension. ('%s' is replaced by username property). |
Any string. |
Due to security reasons, when you do not specify server
and username
or password
properties in arquillian.xml
for Github Governor, this extension looks for system properties github.governor.repository
, github.governor.repositoryuser
, github.governor.token
, github.governor.username
and
github.governor.password
respectively.
You can set properties force
and closePassed
by system properties github.governor.force
and github.governor.closepassed
by setting them to "true" or "false".
Let’s have this test case:
@RunWith(Arquillian.class)
@RunAsClient
public class TestCase
{
@Test
@Github("1")
public void test()
{
//...
}
}
If some Github issue is unresolved, normally, it would be skipped from
execution. However if you force it to execute by force
flag on @Github
annotation, and this test method
passes with success, if you set property closePassed
in your arquillian.xml
, that Github will be
automatically marked as Closed
on Github server.
@RunWith(Arquillian.class)
public class AutomaticClosingTestCase
{
@Test
@Github(value = "2", force = true)
public void automaticClosingTest)
{
// ...
}
}
This extension simply skips test methods which are annotated with @TestSpec
. In order to use this extension, put this into pom.xml
<dependency>
<groupId>org.arquillian.extension</groupId>
<artifactId>arquillian-governor-skipper</artifactId>
<scope>test</scope>
</dependency>
<dependency>
<groupId>org.arquillian.extension</groupId>
<artifactId>arquillian-recorder-reporter-impl</artifactId>
<scope>test</scope>
</dependency>
Configuration of this extension is done via governor-skipper
qualifier:
<extension qualifier="governor-skipper">
<property name="plainAdoc">plain_table.adoc</property>
</extension>
This extension introduces just one annotation you put on your test method. Let’s see it in action:
@Test
@TestSpec(
author = "Stefan Miklosovic",
assertion = "this test should pass",
feature = "tests if true returns true",
issue = "ARQ-1",
prerequisites = "have java",
status = Status.AUTOMATED,
steps = "some steps in order to execute this",
test = "what does this step do"
)
public void someTest() {
Assert.assertTrue(true);
}
If status
is Status.MANUAL
, test method will be skipped from the execution. The generated report gives you
better overview of your test cases, what they do, which methods are automated and which you have to execute manually.
If plainAdoc
property is used, a report will be saved to plain asciidoc table as well. A report will be
added into the tree of Arquillian Report output file in every case.
Configuration property | Description | Default value | Possible values |
---|---|---|---|
plainAdoc |
name of file where plain asciidoc table will be stored |
if this is not set, report to plain adoc will be skipped |
Glad you asked. Because of Arquillian Governor base extension, you are welcome to code your own test method execution resolver as we did with Arquillian JIRA governor extension.
The governor annotation you want to put on your test method (as we did with @Jira
) have
to be annotated with @Governor annotation. @Jira
annotation looks like this:
@Governor // <--- you have to annotate your own annotation with this
@Retention(RetentionPolicy.RUNTIME)
@Target({ ElementType.METHOD })
@Documented
public @interface Jira
{
String value() default "";
boolean force() default false;
}
force
field is optional. This is only specific for JIRA extension, maybe your governor will use something
completely else.
Once you have your governor annotation in your extension, you have to write your own TestExecutionDecider. TestExecutionDecider
implementation has to be registered as a service to your Arquillian extension like this:
public class MyLoadableExtension implements LoadableExtension
{
@Override
public void register(ExtensionBuilder builder)
{
builder.service(TestExecutionDecider.class, MyTestExecutionDecider.class);
builder.service(GovernorProvider.class, BugzillaProvider.class);
}
}
The usage of this SPI is fully explained in official Arquillian Core 1.1.6 release blog post.
As described above, you have to register as a service your own GovernorProvider
which provides the decoding annotation like this:
public class BugzillaProvider implements GovernorProvider
{
@Override
public Class<? extends Annotation> provides()
{
return Bugzilla.class;
}
}
By doing so, you can use @Bugzilla
annotations on your test methods. @Bugzilla
annotation has to be itself annotated with @Governor
annotation the same way as @Jira
annotation is.
Finally, you have to observe ExecutionDecisionEvent
where you have to decide if the annotation in this event which is put on some test method is going to be executed or not.
The example how we did this all for Jira Governor is in class JiraTestExecutionDecider
.
This is the minimal scenario. Of course, your resolution can be done in a completely different way, you could resolve it against database, file, properties or what ever. It is up to you.
In order to release new version, execute following Maven command:
mvn clean release:prepare release:perform
Then:
-
Run test projects in
tests
directory and bump version of governor dependency in them to the to-be-released one -
Verify the build from staging repository
-
Make sure all JIRAs are closed
-
Release version in JIRA and create next version if not available
-
Promote the build to the stable Maven repository
-
Push commits and tag created by maven-release-plugin to the repository.