[xray-exporter] Use scenario title as description for new test cases (#5752)

Author: uarlouski

docs/modules/integrations/pages/xray-exporter.adoc

@@ -60,6 +60,10 @@ Please make sure that the `bdd.configuration.formats` property includes JSON val
 |false
 |Comma-separated list of file and folder paths that should be uploaded to test execution as attachments. Please note that regular files like images, texts are uploaded as is, whereas folders are archived before the upload.
 
+|`xray-exporter.test-case.use-scenario-title-as-description`
+|false
+|If enabled (`true` value), the scenario title will be used as the description, but *only* for newly created test cases, otherwise the description will be left empty.
+
 |===
 
 .application.properties

vividus-to-xray-exporter/src/main/java/org/vividus/xray/configuration/XrayExporterOptions.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2019-2023 the original author or authors.
+ * Copyright 2019-2025 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -30,6 +30,7 @@ public class XrayExporterOptions
     private String testExecutionSummary;
     private List<Path> testExecutionAttachments;
     private boolean testCaseUpdatesEnabled;
+    private TestCase testCase;
 
     public Path getJsonResultsDirectory()
     {
@@ -90,4 +91,29 @@ public void setTestCaseUpdatesEnabled(boolean testCaseUpdatesEnabled)
     {
         this.testCaseUpdatesEnabled = testCaseUpdatesEnabled;
     }
+
+    public TestCase getTestCase()
+    {
+        return testCase;
+    }
+
+    public void setTestCase(TestCase testCase)
+    {
+        this.testCase = testCase;
+    }
+
+    public static final class TestCase
+    {
+        private boolean useScenarioTitleAsDescription;
+
+        public boolean isUseScenarioTitleAsDescription()
+        {
+            return useScenarioTitleAsDescription;
+        }
+
+        public void setUseScenarioTitleAsDescription(boolean useScenarioTitleAsDescription)
+        {
+            this.useScenarioTitleAsDescription = useScenarioTitleAsDescription;
+        }
+    }
 }

vividus-to-xray-exporter/src/main/java/org/vividus/xray/databind/AbstractTestCaseSerializer.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2019-2022 the original author or authors.
+ * Copyright 2019-2025 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -64,6 +64,12 @@ public void serialize(T testCase, JsonGenerator generator, SerializerProvider se
 
             generator.writeStringField("summary", testCase.getSummary());
 
+            String description = testCase.getDescription();
+            if (description != null)
+            {
+                generator.writeStringField("description", testCase.getDescription());
+            }
+
             writeJsonArray(generator, "labels", testCase.getLabels(), false);
 
             writeJsonArray(generator, "components", testCase.getComponents(), true);

vividus-to-xray-exporter/src/main/java/org/vividus/xray/exporter/XrayExporter.java

@@ -154,6 +154,11 @@ private Optional<Entry<String, Scenario>> exportScenario(String storyTitle, Scen
             AbstractTestCase testCase = testCaseFactories.get(testCaseType).apply(parameters);
             if (testCaseId == null)
             {
+                if (xrayExporterOptions.getTestCase().isUseScenarioTitleAsDescription())
+                {
+                    testCase.setDescription(scenario.getTitle());
+                }
+
                 testCaseId = xrayFacade.createTestCase(testCase);
             }
             else if (xrayExporterOptions.isTestCaseUpdatesEnabled())

vividus-to-xray-exporter/src/main/java/org/vividus/xray/model/AbstractTestCase.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2019-2020 the original author or authors.
+ * Copyright 2019-2025 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -24,6 +24,7 @@ public abstract class AbstractTestCase
     private String projectKey;
     private String assignee;
     private String summary;
+    private String description;
     private Set<String> labels;
     private Set<String> components;
 
@@ -67,6 +68,16 @@ public void setSummary(String summary)
         this.summary = summary;
     }
 
+    public String getDescription()
+    {
+        return description;
+    }
+
+    public void setDescription(String description)
+    {
+        this.description = description;
+    }
+
     public Set<String> getLabels()
     {
         return labels;

vividus-to-xray-exporter/src/main/resources/application.properties

@@ -3,3 +3,4 @@ xray-exporter.editable-statuses=
 xray-exporter.jira-instance-key=
 xray-exporter.test-case-updates-enabled=true
 xray-exporter.test-execution-attachments=
+xray-exporter.test-case.use-scenario-title-as-description=false

vividus-to-xray-exporter/src/test/java/org/vividus/xray/databind/ManualTestCaseSerializerTests.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2019-2022 the original author or authors.
+ * Copyright 2019-2025 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -76,6 +76,7 @@ private static ManualTestCase createBaseTest()
         test.setType(TestCaseType.MANUAL.getValue());
         test.setProjectKey(PROJECT_KEY);
         test.setSummary("summary");
+        test.setDescription("description");
         test.setManualTestSteps(List.of(
             createStep("action 1", "data 1", "result 1"),
             createStep("action 2", "data 2", "result 2")

vividus-to-xray-exporter/src/test/java/org/vividus/xray/exporter/XrayExporterTests.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2019-2023 the original author or authors.
+ * Copyright 2019-2025 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -31,6 +31,7 @@
 import static org.mockito.ArgumentMatchers.eq;
 import static org.mockito.Mockito.doThrow;
 import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.never;
 import static org.mockito.Mockito.verify;
 import static org.mockito.Mockito.verifyNoInteractions;
 import static org.mockito.Mockito.verifyNoMoreInteractions;
@@ -72,6 +73,7 @@
 import org.vividus.output.ManualTestStep;
 import org.vividus.util.ResourceUtils;
 import org.vividus.xray.configuration.XrayExporterOptions;
+import org.vividus.xray.configuration.XrayExporterOptions.TestCase;
 import org.vividus.xray.facade.AbstractTestCaseParameters;
 import org.vividus.xray.facade.CucumberTestCaseParameters;
 import org.vividus.xray.facade.ManualTestCaseParameters;
@@ -116,6 +118,7 @@ void beforeEach()
     {
         xrayExporterOptions.setTestCaseUpdatesEnabled(true);
         xrayExporterOptions.setTestExecutionAttachments(List.of(ROOT));
+        xrayExporterOptions.setTestCase(new TestCase());
     }
 
     @AfterEach
@@ -130,6 +133,7 @@ void shouldExportCucumberTestCaseWithoutTestCaseId() throws URISyntaxException,
     {
         URI jsonResultsUri = getJsonResultsUri("createcucumber");
         xrayExporterOptions.setJsonResultsDirectory(Paths.get(jsonResultsUri));
+        xrayExporterOptions.getTestCase().setUseScenarioTitleAsDescription(false);
         CucumberTestCase testCase = mock(CucumberTestCase.class);
 
         when(xrayFacade.createTestCase(testCase)).thenReturn(ISSUE_ID);
@@ -147,6 +151,7 @@ void shouldExportCucumberTestCaseWithoutTestCaseId() throws URISyntaxException,
             + "|parameter-value-3|" + lineSeparator();
         verifyCucumberTestCaseParameters("Scenario Outline", scenario);
         validateLogs(jsonResultsUri, getExportingScenarioEvent(), getExportSuccessfulEvent());
+        verify(testCase, never()).setDescription(any());
     }
 
     @Test
@@ -155,6 +160,7 @@ void shouldUpdateExistingCucumberTestCase() throws URISyntaxException, IOExcepti
     {
         URI jsonResultsUri = getJsonResultsUri(UPDATECUCUMBER_RESOURCE_KEY);
         xrayExporterOptions.setJsonResultsDirectory(Paths.get(jsonResultsUri));
+        xrayExporterOptions.getTestCase().setUseScenarioTitleAsDescription(true);
         CucumberTestCase testCase = mock(CucumberTestCase.class);
 
         when(testCaseFactory.createCucumberTestCase(cucumberTestCaseParametersCaptor.capture())).thenReturn(testCase);
@@ -165,6 +171,7 @@ void shouldUpdateExistingCucumberTestCase() throws URISyntaxException, IOExcepti
         String scenario = GIVEN_STEP + lineSeparator() + WHEN_STEP + lineSeparator() + THEN_STEP;
         verifyCucumberTestCaseParameters("Scenario", scenario);
         validateLogs(jsonResultsUri, getExportingScenarioEvent(), getExportSuccessfulEvent());
+        verify(testCase, never()).setDescription(any());
     }
 
     @Test
@@ -281,10 +288,12 @@ void shouldFailIfResultsDirectoryIsEmpty(@TempDir Path sourceDirectory)
     }
 
     @Test
-    void shouldExportNewTestAndLinkToRequirements() throws URISyntaxException, IOException, JiraConfigurationException
+    void shouldExportNewTestAndLinkToRequirementsAndUseScenarioTitleAsTestCaseDescription()
+            throws URISyntaxException, IOException, JiraConfigurationException
     {
         URI jsonResultsUri = getJsonResultsUri("createandlink");
         xrayExporterOptions.setJsonResultsDirectory(Paths.get(jsonResultsUri));
+        xrayExporterOptions.getTestCase().setUseScenarioTitleAsDescription(true);
         ManualTestCase testCase = mock(ManualTestCase.class);
 
         when(xrayFacade.createTestCase(testCase)).thenReturn(ISSUE_ID);
@@ -296,6 +305,7 @@ void shouldExportNewTestAndLinkToRequirements() throws URISyntaxException, IOExc
 
         verifyManualTestCaseParameters(Set.of(), Set.of());
         validateLogs(jsonResultsUri, getExportingScenarioEvent(), getExportSuccessfulEvent());
+        verify(testCase).setDescription(SCENARIO_TITLE);
     }
 
     @Test

vividus-to-xray-exporter/src/test/resources/org/vividus/xray/databind/manual.json

@@ -13,6 +13,7 @@
       "value": "Manual"
     },
     "summary": "summary",
+    "description": "description",
     "labels": [
       "label 1",
       "label 2"

vividus-to-xray-exporter/src/test/resources/org/vividus/xray/databind/nullable.json

@@ -10,6 +10,7 @@
       "value": "Manual"
     },
     "summary": "summary",
+    "description": "description",
     "manual-steps-field": {
       "steps": [
         {