From 48bed487db414a27557234224c7b8cb76ecc78ec Mon Sep 17 00:00:00 2001
From: Mark Waite <mark.earl.waite@gmail.com>
Date: Mon, 19 Sep 2022 05:37:13 -0600
Subject: [PATCH] Add `testNG` symbol for Pipeline syntax clarity

Allows the Pipeline snippet syntax generator to suggest syntax for
TestNG results and makes it easier to read Pipeline definitions.

Pipeline snippet syntax generator does not correctly handle two boolean
flags, but it feels better to have most of the syntax generator working
rather than hold this change until all of the syntax generator is
working.

Includes an automated test that confirms the symbol `testNG()` works
for scripted Pipeline.  Tested interactively to confirm tha new syntax
is working for declarative Pipeline.  Existing automated test already
checked that the old syntax is still working.
---
 README.md                                     | 27 ++++++++++++++++++-
 .../java/hudson/plugins/testng/Publisher.java |  2 ++
 .../TestNGTestResultBuildActionTest.java      | 23 ++++++++++++++++
 3 files changed, 51 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 0b3583cf..332d1d65 100644
--- a/README.md
+++ b/README.md
@@ -87,14 +87,39 @@ Results**. This option allows you to configure the following properties:
 
 ### Pipeline in Jenkinsfile
 
+The link:https://www.jenkins.io/redirect/pipeline-snippet-generator[Pipeline Syntax Snippet Generator] guides the user to select TestNG report options.
+Add the `testNG` step to declarative Pipeline in a `post` section.
+
 ```
   post {
     always {
-      step([$class: 'Publisher', reportFilenamePattern: '**/testng-results.xml'])
+      testNG()
     }
   }
 ```
 
+Additional options can be included in the testNG declarative Pipeline step like this:
+
+```
+  post {
+    always {
+      testNG(showFailedBuilds: true,
+             unstableFails: 5, unstableSkips: 25,
+             failedFails:  10, failedSkips:   50)
+    }
+  }
+```
+
+The `testNG` Pipeline step can be used in a scripted Pipeline like this:
+
+```
+node {
+  // Add steps that run TestNG tests
+  // Publish TestNG report with the `testNG()` step
+  testNG(reportFilenamePattern: '**/testng-many-results.xml')
+}
+```
+
 ### Properties
 
 Some TestNG plugin properties can only be controlled by command line properties set at Jenkins startup.
diff --git a/src/main/java/hudson/plugins/testng/Publisher.java b/src/main/java/hudson/plugins/testng/Publisher.java
index d56301cf..dcfa6968 100644
--- a/src/main/java/hudson/plugins/testng/Publisher.java
+++ b/src/main/java/hudson/plugins/testng/Publisher.java
@@ -25,6 +25,7 @@
 import hudson.util.FormValidation;
 import jenkins.tasks.SimpleBuildStep;
 import net.sf.json.JSONObject;
+import org.jenkinsci.Symbol;
 import org.kohsuke.stapler.*;
 import org.kohsuke.stapler.verb.POST;
 
@@ -442,6 +443,7 @@ static boolean saveReports(FilePath testngDir, FilePath[] paths, PrintStream log
       return true;
    }
 
+   @Symbol("testNG")
    public static final class DescriptorImpl extends BuildStepDescriptor<hudson.tasks.Publisher> {
 
       /**
diff --git a/src/test/java/hudson/plugins/testng/TestNGTestResultBuildActionTest.java b/src/test/java/hudson/plugins/testng/TestNGTestResultBuildActionTest.java
index 8147a5d1..44cced5b 100644
--- a/src/test/java/hudson/plugins/testng/TestNGTestResultBuildActionTest.java
+++ b/src/test/java/hudson/plugins/testng/TestNGTestResultBuildActionTest.java
@@ -400,6 +400,29 @@ public void test_threshold_for_fails_default_pipeline() throws Exception {
       r.assertLogContains("tests failed, which exceeded threshold of 0%. Marking build as UNSTABLE", build);
    }
 
+   @Issue("JENKINS-27121")
+   @Test
+   public void test_threshold_for_fails_default_pipeline_using_symbol() throws Exception {
+      if (isWindows()) {
+          /* Fails to delete a file on Windows agents of ci.jenkins.io.
+           * Likely indicates a bug somewhere, but I'd rather have most
+           * of the tests passing on ci.jenkins.io Windows rather than
+           * blocking all Windows tests until this can be investigated.
+           */
+          return;
+      }
+      WorkflowJob p = r.jenkins.createProject(WorkflowJob.class, "p");
+      String contents = CommonUtil.getContents(Constants.TESTNG_FAILED_TEST);
+      p.setDefinition(new CpsFlowDefinition("node {\n  writeFile(file: 'testng-results.xml', text: '''" + contents + "''')\n  testNG()\n}\n", true));
+      WorkflowRun build = p.scheduleBuild2(0).get();
+      r.assertBuildStatus(Result.UNSTABLE, build);
+      TestNGTestResultBuildAction action = build.getAction(TestNGTestResultBuildAction.class);
+      assertNotNull(action);
+      TestNGResult result = action.getResult();
+      assertEquals("checking result details", "TestNGResult {totalTests=2, failedTests=1, skippedTests=0, failedConfigs=0, skippedConfigs=0}", result.toString());
+      r.assertLogContains("tests failed, which exceeded threshold of 0%. Marking build as UNSTABLE", build);
+   }
+
   @Test
   public void test_threshold_for_fails_failure() throws Exception {
      FreeStyleProject p = r.createFreeStyleProject();