feat: add a 'description' property into testsuite (#770)

* suite: add a 'description' property

This attribute expects a markdown content.

If defined, the html output will render it in the 'info' header of the
test stuite.

* suite description: add a use example in README

Signed-off-by: Christophe de Vienne <[email protected]>

Author: cdevienne

README.md

@@ -299,6 +299,7 @@ In `venom` a testsuite is written in one `YAML` file respecting the following st
 ```yaml
 
 name: Title of TestSuite
+description: A detailed description of the TestSuite, in markdown.
 testcases:
 - name: TestCase with default value, exec cmd. Check if exit code != 1
   steps:

process_files.go

@@ -119,10 +119,11 @@ func (v *Venom) readFiles(ctx context.Context, filesPath []string) (err error) {
 		}
 
 		ts := TestSuite{
-			Name:      testSuiteInput.Name,
-			TestCases: make([]TestCase, len(testSuiteInput.TestCases)),
-			Vars:      testSuiteInput.Vars,
-			Secrets:   testSuiteInput.Secrets,
+			Name:        testSuiteInput.Name,
+			Description: testSuiteInput.Description,
+			TestCases:   make([]TestCase, len(testSuiteInput.TestCases)),
+			Vars:        testSuiteInput.Vars,
+			Secrets:     testSuiteInput.Secrets,
 		}
 		for i := range testSuiteInput.TestCases {
 			ts.TestCases[i] = TestCase{

types.go

@@ -104,17 +104,19 @@ type TestSuiteXML struct {
 }
 
 type TestSuiteInput struct {
-	Name      string          `json:"name" yaml:"name"`
-	TestCases []TestCaseInput `json:"testcases" yaml:"testcases"`
-	Vars      H               `json:"vars" yaml:"vars"`
-	Secrets   []string        `json:"secrets" yaml:"secrets"`
+	Name        string          `json:"name" yaml:"name"`
+	Description string          `json:"description" yaml:"description"`
+	TestCases   []TestCaseInput `json:"testcases" yaml:"testcases"`
+	Vars        H               `json:"vars" yaml:"vars"`
+	Secrets     []string        `json:"secrets" yaml:"secrets"`
 }
 
 type TestSuite struct {
-	Name      string     `json:"name" yaml:"name"`
-	TestCases []TestCase `json:"testcases" yaml:"testcases"`
-	Vars      H          `json:"vars" yaml:"vars"`
-	Secrets   []string   `json:"secrets" yaml:"secrets"`
+	Name        string     `json:"name" yaml:"name"`
+	Description string     `json:"description,omitempty" yaml:"description"`
+	TestCases   []TestCase `json:"testcases" yaml:"testcases"`
+	Vars        H          `json:"vars" yaml:"vars"`
+	Secrets     []string   `json:"secrets" yaml:"secrets"`
 
 	// computed
 	ShortName    string `json:"shortname" yaml:"-"`
@@ -357,8 +359,10 @@ func RemoveNotPrintableChar(in string) string {
 	return strings.Map(m, in)
 }
 
-var Red = color.New(color.FgRed).SprintFunc()
-var Yellow = color.New(color.FgYellow).SprintFunc()
-var Green = color.New(color.FgGreen).SprintFunc()
-var Cyan = color.New(color.FgCyan).SprintFunc()
-var Gray = color.New(color.Attribute(90)).SprintFunc()
+var (
+	Red    = color.New(color.FgRed).SprintFunc()
+	Yellow = color.New(color.FgYellow).SprintFunc()
+	Green  = color.New(color.FgGreen).SprintFunc()
+	Cyan   = color.New(color.FgCyan).SprintFunc()
+	Gray   = color.New(color.Attribute(90)).SprintFunc()
+)

venom_output.html

@@ -8,6 +8,7 @@
     <script src="https://cdnjs.cloudflare.com/ajax/libs/jquery/3.6.0/jquery.min.js" integrity="sha512-894YE6QWD5I59HgZOGReFYm4dnWc1Qt5NtvYSaNcOP+u1T9qYdvdihz0PPSiiqn/+/3e7Jo4EaG7TubfWGUrMQ==" crossorigin="anonymous" referrerpolicy="no-referrer"></script>
     <script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/js/bootstrap.bundle.min.js" integrity="sha384-A3rJD856KowSb7dwlZdYEkO39Gagi7vIsF0jrRAoQmDKKtQBHUuLZ9AsSv4jD4Xa" crossorigin="anonymous"></script>
     <script src="https://cdnjs.cloudflare.com/ajax/libs/yamljs/0.3.0/yaml.min.js"></script>
+    <script src="https://cdnjs.cloudflare.com/ajax/libs/showdown/2.1.0/showdown.min.js"></script>
     <style>
 
     @media (min-width: 768px) {
@@ -209,6 +210,11 @@ <h5 class="modal-title" id="varsModalLabel">Test Suite Variables</h5>
         var data = a.test_suites[this.id];
 
         var info = "";
+        if (data.description) {
+            var converter = new showdown.Converter(),
+                html      = converter.makeHtml(data.description);
+            info += html;
+        }
         info += '<ul>'
 
         info += '<li>Filepath: <code class="nt">'+data.filepath+'</code></li>';