From 38dc7813ee6f7d68cbeb3213117432d07cbb33ad Mon Sep 17 00:00:00 2001
From: Dmitry Ermakovich <dmitry.ermakovich@testit.software>
Date: Fri, 22 Nov 2024 09:01:56 +0300
Subject: [PATCH] fix: TMS-29851: update docs

---
 README.md                                     | 219 +++++++++++++++++-
 testit-adapter-kotest/Readme.md               |   4 +-
 testit-adapter-kotest/build.gradle.kts        |   2 +-
 .../ru/testit/listener/StepDescribeTests.kt   | 142 ------------
 testit-kotlin-commons/build.gradle.kts        |   2 +-
 5 files changed, 221 insertions(+), 148 deletions(-)
 delete mode 100644 testit-adapter-kotest/src/test/kotlin/ru/testit/listener/StepDescribeTests.kt

diff --git a/README.md b/README.md
index 39bb1b7..1213a71 100644
--- a/README.md
+++ b/README.md
@@ -11,5 +11,220 @@ Supported test frameworks :
  1. [Kotest](https://kotest.io/docs/framework/framework.html)
 
 
-# 🚀 Warning
-- If value from @WorkItemIds annotation not found in TMS then test result will NOT be uploaded.
\ No newline at end of file
+#### 🚀 Warning
+- If value from @WorkItemIds annotation not found in TMS then test result will NOT be uploaded.
+
+
+## Metadata of autotest
+
+Use metadata to specify information about autotest.
+
+
+Description of metadata:
+
+* `externalId` - unique internal autotest ID (used in Test IT)
+* `links` - links listed in the autotest card
+* `workItemIds` - a value that links autotests with manual tests. Receives the array of manual tests' IDs
+* `attachments` - autotests attachments list
+* `name` - internal autotest name (used in Test IT)
+* `title` - autotest name specified in the autotest card. If not specified, the name from the displayName method is used
+* `message` - autotest message
+* `itemStatus` - autotest itemStatus 
+* `description` - autotest description specified in the autotest card
+* `labels` - tags listed in the autotest card
+
+
+All autotest metadata described with `TestItContext` class using `testCase.setContext()`: 
+
+```kotlin
+data class TestItContext (
+    var uuid: String? = null,
+    var externalId: String? = null,
+    var links: MutableList<LinkItem>? = null,
+    var workItemIds: MutableList<String>? = null,
+    var attachments: MutableList<String>? = null,
+    var name: String? = null,
+    var title: String? = null,
+    var message: String? = null,
+    var itemStatus: ItemStatus? = null,
+    var description: String? = null,
+    var parameters: MutableMap<String, String>? = null,
+    var labels: MutableList<Label>? = null,
+)
+```
+
+Example: 
+
+```kotlin
+ testCase.setContext(TestItContext(
+    name = "isPythagTriple($a, $b, $c)",
+    labels = mutableListOf(Label("123"))
+))
+```
+
+
+
+## Examples
+
+### Default example:
+
+```kotlin
+package org.example.tests
+
+import io.kotest.core.spec.style.DescribeSpec
+import io.kotest.matchers.shouldBe
+import ru.testit.listener.TestItReporter
+import ru.testit.models.LinkItem
+import ru.testit.models.LinkType
+import ru.testit.models.TestItContext
+import ru.testit.utils.*
+
+// isStepContainer true, 2 tests, before + after(failed): failed
+class BeforePassedAfterPassed : DescribeSpec({
+    // enable steps by true parameter
+    extensions(TestItReporter(true))
+    beforeTest {
+    }
+    // executes even if beforeTest is failed
+    afterTest {
+        it.testItAfterTest {
+            "afterTest" shouldBe "failed"
+        }
+    }
+    it("test1 passed, afterTest failed -> failed") {
+        3 + 4 shouldBe 7
+    }
+    it("test2 failed, afterTest failed -> failed") {
+        "TestBody" shouldBe "Failed"
+    }
+})
+
+```
+
+
+### Steps container example
+
+```kotlin
+package org.example.tests
+
+import io.kotest.core.spec.style.DescribeSpec
+import io.kotest.matchers.shouldBe
+import ru.testit.listener.TestItReporter
+import ru.testit.models.LinkItem
+import ru.testit.models.LinkType
+import ru.testit.models.TestItContext
+import ru.testit.utils.*
+
+// isStepContainer true, 1 test, 2 steps before + after(failed): ok + failed
+class BeforeAfterSteps : DescribeSpec({
+    extensions(TestItReporter(true))
+
+    beforeTest {
+        it.setSetupName("beforeTest")
+    }
+
+    // executes even if beforeTest is failed
+    afterTest {
+        it.a.setTeardownName("afterTest")
+        it.testItAfterTest {
+        }
+    }
+
+    describe("describe step container test") {
+        testCase.asStepContainer()
+        testCase.setContext(
+            TestItContext(
+                links = mutableListOf(
+                    LinkItem(url = "https://google.com", title = "",
+                    description = "", type = LinkType.BLOCKED_BY)
+                )
+            )
+        )
+        it("an inner step1 - failed") {
+            "Step1" shouldBe "Failed"
+        }
+        it("an inner step2 - pass") {
+            3 + 4 shouldBe 7
+        }
+    }
+})
+```
+
+### Step container with FunSpec style
+
+```kotlin
+package org.example.tests
+
+import io.kotest.core.spec.style.FunSpec
+import io.kotest.matchers.shouldBe
+import ru.testit.listener.TestItReporter
+import ru.testit.models.Label
+import ru.testit.models.TestItContext
+import ru.testit.utils.asStepContainer
+import ru.testit.utils.setContext
+
+class StepContextTest : FunSpec({
+   extensions(TestItReporter(true, ))
+
+
+   context("fun step spec test") {
+       testCase.asStepContainer()
+       testCase.setContext(TestItContext(
+           labels = mutableListOf(Label("some label1"))
+       ))
+
+       test("shouldFail_") {
+           true shouldBe false
+       }
+
+       test("shouldPass") {
+           true shouldBe true
+       }
+   }
+
+})
+
+```
+
+### Parametrized test example
+
+```kotlin
+package org.example.tests
+
+import io.kotest.core.spec.style.FunSpec
+import io.kotest.datatest.withData
+import io.kotest.matchers.shouldBe
+import ru.testit.listener.TestItReporter
+import ru.testit.models.Label
+import ru.testit.models.TestItContext
+import ru.testit.utils.setContext
+import ru.testit.utils.testItAfterTest
+
+
+data class PythagTriple(val a: Int, val b: Int, val c: Int)
+fun isPythagTriple(a: Int, b: Int, c: Int): Boolean = a * a + b * b == c * c
+
+
+class NestingTest : FunSpec({
+   val testit = TestItReporter(true)
+   extensions(testit)
+
+   context("Pythag triples tests") {
+       withData(
+           PythagTriple(3, 4, 5),
+           PythagTriple(6, 8, 10),
+           PythagTriple(8, 15, 17),
+           PythagTriple(7, 24, 25),
+           PythagTriple(7, 7, 7),
+
+           ) { (a, b, c) ->
+           testCase.setContext(TestItContext(
+               name = "isPythagTriple($a, $b, $c)",
+               labels = mutableListOf(Label("123"))
+           ))
+           isPythagTriple(a, b, c) shouldBe true
+       }
+   }
+
+})
+```
\ No newline at end of file
diff --git a/testit-adapter-kotest/Readme.md b/testit-adapter-kotest/Readme.md
index 317ba3f..ff1e507 100644
--- a/testit-adapter-kotest/Readme.md
+++ b/testit-adapter-kotest/Readme.md
@@ -13,7 +13,7 @@ Add this dependency to your project POM:
 <dependency>
     <groupId>ru.testit</groupId>
     <artifactId>testit-adapter-kotest</artifactId>
-    <version>0.1.0</version>
+    <version>0.1.1</version>
     <scope>compile</scope>
 </dependency>
 ```
@@ -23,7 +23,7 @@ Add this dependency to your project POM:
 Add this dependency to your project build file:
 
 ```groovy
-implementation "ru.testit:testit-adapter-kotest:0.1.0"
+implementation "ru.testit:testit-adapter-kotest:0.1.1"
 ```
 
 
diff --git a/testit-adapter-kotest/build.gradle.kts b/testit-adapter-kotest/build.gradle.kts
index 4e147b1..e6bb389 100644
--- a/testit-adapter-kotest/build.gradle.kts
+++ b/testit-adapter-kotest/build.gradle.kts
@@ -7,7 +7,7 @@ plugins {
 }
 
 group = "ru.testit"
-version = "0.1.0"
+version = "0.1.1"
 
 java {
     withJavadocJar()
diff --git a/testit-adapter-kotest/src/test/kotlin/ru/testit/listener/StepDescribeTests.kt b/testit-adapter-kotest/src/test/kotlin/ru/testit/listener/StepDescribeTests.kt
deleted file mode 100644
index ecbb8eb..0000000
--- a/testit-adapter-kotest/src/test/kotlin/ru/testit/listener/StepDescribeTests.kt
+++ /dev/null
@@ -1,142 +0,0 @@
-// package ru.testit.listener
-
-// import io.kotest.core.Tuple2
-// import io.kotest.core.spec.AfterTest
-// import io.kotest.core.spec.style.DescribeSpec
-// import io.kotest.core.test.TestCase
-// import io.kotest.core.test.TestResult
-// import io.kotest.matchers.should
-// import io.kotest.matchers.shouldBe
-// import ru.testit.models.LinkItem
-// import ru.testit.models.LinkType
-// import ru.testit.models.TestItContext
-// import ru.testit.utils.*
-
-// /***/
-
-// // isStepContainer true, 2 tests, before(failed) + after(failed): failed both
-// class BeforeAfterFailed : DescribeSpec({
-//     extensions(TestItReporter(true))
-//     beforeTest {
-//         "beforeTest" shouldBe "Failed"
-//     }
-//     // executes even if beforeTest is failed
-//     afterTest {
-//         it.testItAfterTest {
-//             "afterTest" shouldBe "Failed"
-//         }
-//     }
-//     it("before failed, test1 body pass -> failed") {
-//         3 + 4 shouldBe 7
-//     }
-//     it("before failed, test2 body failed -> failed") {
-//         "TestBody" shouldBe "Failed"
-//     }
-// })
-
-// // isStepContainer true, 2 tests, before + after: ok + failed
-// class BeforeAfterPassed : DescribeSpec({
-//     extensions(TestItReporter(true))
-//     beforeTest {
-//     }
-//     // executes even if beforeTest is failed
-//     afterTest {
-//         it.testItAfterTest {
-//         }
-//     }
-//     it("test1 passed") {
-//         3 + 4 shouldBe 7
-//     }
-//     it("test2 failed") {
-//         "TestBody" shouldBe "Failed"
-//     }
-// })
-
-// // isStepContainer true, 2 tests, before + after(failed): failed
-// class BeforePassedAfterPassed : DescribeSpec({
-//     extensions(TestItReporter(true))
-//     beforeTest {
-//     }
-//     // executes even if beforeTest is failed
-//     afterTest {
-//         it.testItAfterTest {
-//             "afterTest" shouldBe "failed"
-//         }
-//     }
-//     it("test1 passed, afterTest failed -> failed") {
-//         3 + 4 shouldBe 7
-//     }
-//     it("test2 failed, afterTest failed -> failed") {
-//         "TestBody" shouldBe "Failed"
-//     }
-// })
-
-//  /**/
-// // isStepContainer true, 1 test, 2 steps before + after(failed): ok + failed
-// class BeforeAfterSteps : DescribeSpec({
-//     extensions(TestItReporter(true))
-
-//     beforeTest {
-//         it.setSetupName("beforeTest")
-//     }
-
-//     // executes even if beforeTest is failed
-//     afterTest {
-//         it.a.setTeardownName("afterTest")
-//         it.testItAfterTest {
-//         }
-//     }
-
-//     describe("describe step container test") {
-//         testCase.asStepContainer()
-//         testCase.setContext(
-//             TestItContext(
-//                 links = mutableListOf(
-//                     LinkItem(url = "https://google.com", title = "",
-//                     description = "", type = LinkType.BLOCKED_BY)
-//                 )
-//             )
-//         )
-//         it("an inner step1 - failed") {
-//             "Step1" shouldBe "Failed"
-//         }
-//         it("an inner step2 - pass") {
-//             3 + 4 shouldBe 7
-//         }
-//     }
-// })
-
-
-// // isStepContainer false, 2 tests, before + after(failed): ok + failed
-// class BeforeAfterStepsContainerFalse : DescribeSpec({
-//     extensions(TestItReporter(isStepContainers = false))
-
-//     beforeTest {
-//         it.setSetupName("beforeTest")
-//     }
-
-//     // executes even if beforeTest is failed
-//     afterTest {
-//         it.testItAfterTest("afterTest", {
-//             1 shouldBe 1
-//         })
-//     }
-
-//     describe("describe step container test") {
-//         testCase.asStepContainer() // doesn't work because isStepContainers false
-//         testCase.setContext(
-//             TestItContext(
-//                 links = mutableListOf(
-//                     LinkItem(url = "https://google.com", title = "",
-//                         description = "", type = LinkType.BLOCKED_BY)
-//                 )
-//             )
-//         )
-//         it("test1 - failed") {
-//             "Step1" shouldBe "Failed"
-//         }
-//         it("test2 - pass") {
-//             3 + 4 shouldBe 7
-//         }
-//     }
-// })
diff --git a/testit-kotlin-commons/build.gradle.kts b/testit-kotlin-commons/build.gradle.kts
index 6fd778f..c7e12cf 100644
--- a/testit-kotlin-commons/build.gradle.kts
+++ b/testit-kotlin-commons/build.gradle.kts
@@ -6,7 +6,7 @@ plugins {
 }
 
 group = "ru.testit"
-version = "0.1.0"
+version = "0.1.1"
 
 val slf4jVersion = "1.7.2"