From 4c8de7f2c028be5b6c94ead9b5b940a050f8a892 Mon Sep 17 00:00:00 2001 From: Krishnan Mahadevan Date: Thu, 18 Jan 2024 12:01:12 +0530 Subject: [PATCH] Documentation for IConfigurable Closes #58 --- src/main/asciidoc/docs/iconfigurable.adoc | 76 ++++++++++++++++++++ src/main/asciidoc/docs/ihookable.adoc | 2 +- src/main/asciidoc/docs/testng_listeners.adoc | 2 +- src/main/asciidoc/documentation.adoc | 2 + 4 files changed, 80 insertions(+), 2 deletions(-) create mode 100644 src/main/asciidoc/docs/iconfigurable.adoc diff --git a/src/main/asciidoc/docs/iconfigurable.adoc b/src/main/asciidoc/docs/iconfigurable.adoc new file mode 100644 index 0000000..4154ca7 --- /dev/null +++ b/src/main/asciidoc/docs/iconfigurable.adoc @@ -0,0 +1,76 @@ +=== Overriding configuration methods + +:url: https://javadoc.io/static/org.testng/testng/{version-label} + +TestNG allows you to override and possibly skip the invocation of configuration methods. +You achieve this by implementing the interface {url}/org/testng/IConfigurable.html[IConfigurable] inside either your test class (or) in your base class from which your test classes extend. + +Below is a complete sample. + +Sample base class: + +[source, java] + +---- +import org.testng.IConfigurable; +import org.testng.IConfigureCallBack; +import org.testng.ITestResult; +import org.testng.SkipException; +import org.testng.annotations.CustomAttribute; +import org.testng.annotations.Test; + +import java.lang.reflect.Method; +import java.util.Arrays; +import java.util.Optional; + +public class AbstractTestCase implements IConfigurable { + protected static final String OMIT_CONFIG = "omit-config"; + + @Override + public void run(IConfigureCallBack callBack, ITestResult testResult) { + //Look for the Method parameter on our configuration method + Optional foundTestMethod = Arrays.stream(testResult.getParameters()) + .filter(it -> (it instanceof Method)) + .map(it -> (Method) it) + .findFirst(); + if (foundTestMethod.isPresent()) { + // We found our configuration method. + Method found = foundTestMethod.get(); + CustomAttribute[] attributes = found.getAnnotation(Test.class).attributes(); + // We now check for the custom attribute that indicates our configuration method needs to be skipped. + boolean skip = Arrays.stream(attributes).anyMatch(it -> OMIT_CONFIG.equalsIgnoreCase(it.name())); + if (skip) { + throw new SkipException("Skipping execution of config method " + testResult.getMethod().getQualifiedName()); + } + } + // If we are here, then it means we just need to execute the configuration method. + callBack.runConfigurationMethod(testResult); + } +} +---- + +A test class that extends the above base class can look like below: + +[source, java] + +---- +import org.testng.annotations.BeforeMethod; +import org.testng.annotations.CustomAttribute; +import org.testng.annotations.Test; + +import java.lang.reflect.Method; + +public class SampleTestCase extends AbstractTestCase { + + //We would like to ignore skips and have TestNG run this config method always + @BeforeMethod(ignoreFailure = true) + public void setup(Method method) {} + + //We would like to skip configuration for this test + @Test(attributes = { @CustomAttribute(name = OMIT_CONFIG) }) + public void testMethod1() {} + + @Test + public void testMethod2() {} +} +---- diff --git a/src/main/asciidoc/docs/ihookable.adoc b/src/main/asciidoc/docs/ihookable.adoc index 3d7b14e..5cd5f10 100644 --- a/src/main/asciidoc/docs/ihookable.adoc +++ b/src/main/asciidoc/docs/ihookable.adoc @@ -3,7 +3,7 @@ :url: https://javadoc.io/static/org.testng/testng/{version-label} TestNG allows you to override and possibly skip the invocation of test methods. -One example of where this is useful is if you need to your test methods with a specific security manager. You achieve this by providing a listener that implements {url}/org/testng/IHookable.html[IHookable]. +One example of where this is useful is if you need to your test methods with a specific security manager. You achieve this by implementing the interface {url}/org/testng/IHookable.html[IHookable] inside either your test class (or) in your base class from which your test classes extend. Here is an example with JAAS: diff --git a/src/main/asciidoc/docs/testng_listeners.adoc b/src/main/asciidoc/docs/testng_listeners.adoc index 00c9aaa..69d471d 100644 --- a/src/main/asciidoc/docs/testng_listeners.adoc +++ b/src/main/asciidoc/docs/testng_listeners.adoc @@ -10,7 +10,7 @@ There are several interfaces that allow you to modify TestNG's behavior. These i * IExecutionListener(doc, {javadocs-base-url}/org/testng/IExecutionListener.html[javadoc]) * IExecutionVisualiser(doc, {javadocs-base-url}/org/testng/IExecutionVisualiser.html[javadoc]) * IHookable (xref:ihookable.adoc[doc], {javadocs-base-url}/org/testng/IHookable.html[javadoc]) -* IConfigurable(doc, {javadocs-base-url}/org/testng/IConfigurable.html[javadoc]) +* IConfigurable(xref:iconfigurable.adoc[doc], {javadocs-base-url}/org/testng/IConfigurable.html[javadoc]) * IInvokedMethodListener (doc, {javadocs-base-url}/org/testng/IInvokedMethodListener.html[javadoc]) * IMethodInterceptor (xref:method_interceptors.adoc[doc], {javadocs-base-url}/org/testng/IMethodInterceptor.html[javadoc]) * IReporter (xref:logging_and_results.adoc#_logging_reporters[doc], {javadocs-base-url}/org/testng/IReporter.html[javadoc]) diff --git a/src/main/asciidoc/documentation.adoc b/src/main/asciidoc/documentation.adoc index dccb84c..09c2a1a 100644 --- a/src/main/asciidoc/documentation.adoc +++ b/src/main/asciidoc/documentation.adoc @@ -42,6 +42,8 @@ include::docs/method_invocations.adoc[] include::docs/ihookable.adoc[] +include::docs/iconfigurable.adoc[] + include::docs/altering_suites.adoc[] include::test_results.adoc[]