feat(output): add output formatter framework (text/json/yaml/github-actions)

Signed-off-by: caesarsage <destinyerhabor6@gmail.com>

Author: Caesarsage

pkg/output/formatter.go

@@ -0,0 +1,68 @@
+/*
+ * Copyright The Microcks Authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *  http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+// Package output renders a completed Microcks TestResult in a selectable format
+// (text, json, yaml, github-actions) for the `microcks test --output` flag.
+package output
+
+import (
+	"fmt"
+
+	"github.com/microcks/microcks-cli/pkg/connectors"
+)
+
+// OutputFormat is a supported value of the --output flag.
+type OutputFormat string
+
+const (
+	FormatText          OutputFormat = "text"
+	FormatJSON          OutputFormat = "json"
+	FormatYAML          OutputFormat = "yaml"
+	FormatGitHubActions OutputFormat = "github-actions"
+)
+
+// Formatter renders a completed TestResult for a chosen output target. The
+// returned string is written to stdout by the caller; formatters that also have
+// side effects (e.g. github-actions writing the job step summary) perform them
+// during Format.
+type Formatter interface {
+	Format(result *connectors.TestResult) (string, error)
+}
+
+// NewFormatter returns the Formatter for the given format.
+func NewFormatter(format OutputFormat) (Formatter, error) {
+	switch format {
+	case FormatText:
+		return &TextFormatter{}, nil
+	case FormatJSON:
+		return &JSONFormatter{}, nil
+	case FormatYAML:
+		return &YAMLFormatter{}, nil
+	case FormatGitHubActions:
+		return &GitHubActionsFormatter{}, nil
+	default:
+		return nil, fmt.Errorf("unsupported output format %q (use: text, json, yaml, github-actions)", format)
+	}
+}
+
+// IsValid reports whether s is a supported output format.
+func IsValid(s string) bool {
+	switch OutputFormat(s) {
+	case FormatText, FormatJSON, FormatYAML, FormatGitHubActions:
+		return true
+	}
+	return false
+}

pkg/output/github_actions_formatter.go

@@ -0,0 +1,128 @@
+/*
+ * Copyright The Microcks Authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *  http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package output
+
+import (
+	"fmt"
+	"os"
+	"strings"
+
+	"github.com/microcks/microcks-cli/pkg/connectors"
+)
+
+// GitHubActionsFormatter renders the result as GitHub Actions workflow commands:
+// a collapsible ::group:: per operation, ::error:: annotations for failures
+// (and ::notice:: for passes when MICROCKS_ACTIONS_VERBOSE is set), plus a
+// markdown table appended to $GITHUB_STEP_SUMMARY.
+type GitHubActionsFormatter struct{}
+
+func (f *GitHubActionsFormatter) Format(r *connectors.TestResult) (string, error) {
+	verbose := os.Getenv("MICROCKS_ACTIONS_VERBOSE") != ""
+
+	var b strings.Builder
+	for _, tc := range r.TestCaseResults {
+		icon := "✅"
+		if !tc.Success {
+			icon = "❌"
+		}
+		fmt.Fprintf(&b, "::group::%s %s\n", icon, tc.OperationName)
+		for _, s := range tc.TestStepResults {
+			switch {
+			case !s.Success:
+				fmt.Fprintf(&b, "::error title=%s::%s\n",
+					escapeProperty(tc.OperationName), escapeData(stepMessage(s)))
+			case verbose:
+				fmt.Fprintf(&b, "::notice title=%s::%s passed\n",
+					escapeProperty(tc.OperationName), escapeData(s.RequestName))
+			}
+		}
+		fmt.Fprintf(&b, "::endgroup::\n")
+	}
+
+	if r.Success {
+		fmt.Fprintf(&b, "::notice title=Microcks contract test::All %d operation(s) conform to the contract\n",
+			len(r.TestCaseResults))
+	} else {
+		fmt.Fprintf(&b, "::error title=Microcks contract test::Contract test failed - see annotations above\n")
+	}
+
+	if err := writeStepSummary(r); err != nil {
+		// The step summary is best-effort; never fail the run over it.
+		fmt.Fprintf(&b, "::warning::could not write GITHUB_STEP_SUMMARY: %s\n", escapeData(err.Error()))
+	}
+
+	return b.String(), nil
+}
+
+// stepMessage returns the failure message, or a sensible default when empty.
+func stepMessage(s connectors.TestStepResult) string {
+	if strings.TrimSpace(s.Message) != "" {
+		return s.Message
+	}
+	if s.RequestName != "" {
+		return s.RequestName + " did not conform to the contract"
+	}
+	return "did not conform to the contract"
+}
+
+// writeStepSummary appends a per-operation markdown table to the GitHub job
+// summary file, if GITHUB_STEP_SUMMARY is set.
+func writeStepSummary(r *connectors.TestResult) error {
+	path := os.Getenv("GITHUB_STEP_SUMMARY")
+	if path == "" {
+		return nil
+	}
+
+	var b strings.Builder
+	b.WriteString("## Microcks contract test\n\n")
+	b.WriteString(fmt.Sprintf("**Overall:** %s\n\n", passFail(r.Success)))
+	b.WriteString("| Operation | Result |\n| --- | --- |\n")
+	for _, tc := range r.TestCaseResults {
+		b.WriteString(fmt.Sprintf("| %s | %s |\n", tc.OperationName, passFail(tc.Success)))
+	}
+	b.WriteString("\n")
+
+	file, err := os.OpenFile(path, os.O_APPEND|os.O_WRONLY|os.O_CREATE, 0o644)
+	if err != nil {
+		return err
+	}
+	defer file.Close()
+	_, err = file.WriteString(b.String())
+	return err
+}
+
+func passFail(ok bool) string {
+	if ok {
+		return "✅ pass"
+	}
+	return "❌ fail"
+}
+
+// escapeData escapes a GitHub Actions command message per the workflow-command spec.
+func escapeData(s string) string {
+	s = strings.ReplaceAll(s, "%", "%25")
+	s = strings.ReplaceAll(s, "\r", "%0D")
+	s = strings.ReplaceAll(s, "\n", "%0A")
+	return s
+}
+
+// escapeProperty escapes a GitHub Actions command property value.
+func escapeProperty(s string) string {
+	s = escapeData(s)
+	s = strings.ReplaceAll(s, ":", "%3A")
+	s = strings.ReplaceAll(s, ",", "%2C")
+	return s
+}

pkg/output/json_formatter.go

@@ -0,0 +1,33 @@
+/*
+ * Copyright The Microcks Authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *  http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package output
+
+import (
+	"encoding/json"
+
+	"github.com/microcks/microcks-cli/pkg/connectors"
+)
+
+// JSONFormatter renders the test result as indented JSON.
+type JSONFormatter struct{}
+
+func (f *JSONFormatter) Format(r *connectors.TestResult) (string, error) {
+	b, err := json.MarshalIndent(r, "", "  ")
+	if err != nil {
+		return "", err
+	}
+	return string(b), nil
+}

pkg/output/output_test.go

@@ -0,0 +1,155 @@
+/*
+ * Copyright The Microcks Authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *  http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package output
+
+import (
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"github.com/microcks/microcks-cli/pkg/connectors"
+)
+
+func sampleResult() *connectors.TestResult {
+	return &connectors.TestResult{
+		ID:          "abc123",
+		Success:     false,
+		ElapsedTime: 1500,
+		TestCaseResults: []connectors.TestCaseResult{
+			{Success: true, OperationName: "GET /products", TestStepResults: []connectors.TestStepResult{
+				{Success: true, RequestName: "all"},
+			}},
+			{Success: false, OperationName: "POST /orders", TestStepResults: []connectors.TestStepResult{
+				{Success: false, RequestName: "new", Message: "price: expected number\ngot string"},
+			}},
+		},
+	}
+}
+
+func TestNewFormatterAndIsValid(t *testing.T) {
+	for _, f := range []string{"text", "json", "yaml", "github-actions"} {
+		if !IsValid(f) {
+			t.Errorf("expected %q to be valid", f)
+		}
+		if _, err := NewFormatter(OutputFormat(f)); err != nil {
+			t.Errorf("NewFormatter(%q) errored: %v", f, err)
+		}
+	}
+	if IsValid("xml") {
+		t.Error("expected xml to be invalid")
+	}
+	if _, err := NewFormatter("xml"); err == nil {
+		t.Error("expected NewFormatter(xml) to error")
+	}
+}
+
+func TestTextFormatter(t *testing.T) {
+	out, err := (&TextFormatter{}).Format(sampleResult())
+	if err != nil {
+		t.Fatal(err)
+	}
+	for _, want := range []string{"FAILURE", "[PASS] GET /products", "[FAIL] POST /orders", "price: expected number"} {
+		if !strings.Contains(out, want) {
+			t.Errorf("text output missing %q\n%s", want, out)
+		}
+	}
+}
+
+func TestJSONFormatter(t *testing.T) {
+	out, err := (&JSONFormatter{}).Format(sampleResult())
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !strings.Contains(out, `"id": "abc123"`) || !strings.Contains(out, `"operationName": "POST /orders"`) {
+		t.Errorf("json output unexpected:\n%s", out)
+	}
+}
+
+func TestYAMLFormatter(t *testing.T) {
+	out, err := (&YAMLFormatter{}).Format(sampleResult())
+	if err != nil {
+		t.Fatal(err)
+	}
+	// Keys should be camelCase (json field names), not Go field names.
+	if !strings.Contains(out, "id: abc123") || !strings.Contains(out, "testCaseResults:") {
+		t.Errorf("yaml output unexpected:\n%s", out)
+	}
+}
+
+func TestGitHubActionsFormatter(t *testing.T) {
+	out, err := (&GitHubActionsFormatter{}).Format(sampleResult())
+	if err != nil {
+		t.Fatal(err)
+	}
+	checks := []string{
+		"::group::",
+		"GET /products",
+		"::error title=POST /orders::",
+		"price: expected number%0Agot string", // newline escaped in data; colon only escaped in properties
+		"::endgroup::",
+		"::error title=Microcks contract test::",
+	}
+	for _, want := range checks {
+		if !strings.Contains(out, want) {
+			t.Errorf("github-actions output missing %q\n%s", want, out)
+		}
+	}
+	// No ::notice:: for the passing op unless verbose.
+	if strings.Contains(out, "::notice title=GET /products::") {
+		t.Errorf("unexpected ::notice:: without verbose:\n%s", out)
+	}
+}
+
+func TestGitHubActionsVerbose(t *testing.T) {
+	t.Setenv("MICROCKS_ACTIONS_VERBOSE", "1")
+	out, err := (&GitHubActionsFormatter{}).Format(sampleResult())
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !strings.Contains(out, "::notice title=GET /products::") {
+		t.Errorf("expected ::notice:: for passing op in verbose mode:\n%s", out)
+	}
+}
+
+func TestGitHubActionsStepSummary(t *testing.T) {
+	summary := filepath.Join(t.TempDir(), "summary.md")
+	t.Setenv("GITHUB_STEP_SUMMARY", summary)
+
+	if _, err := (&GitHubActionsFormatter{}).Format(sampleResult()); err != nil {
+		t.Fatal(err)
+	}
+
+	data, err := os.ReadFile(summary)
+	if err != nil {
+		t.Fatalf("step summary not written: %v", err)
+	}
+	s := string(data)
+	for _, want := range []string{"## Microcks contract test", "| Operation | Result |", "GET /products", "POST /orders"} {
+		if !strings.Contains(s, want) {
+			t.Errorf("step summary missing %q\n%s", want, s)
+		}
+	}
+}
+
+func TestEscaping(t *testing.T) {
+	if got := escapeData("a%b\nc\rd"); got != "a%25b%0Ac%0Dd" {
+		t.Errorf("escapeData = %q", got)
+	}
+	if got := escapeProperty("a:b,c"); got != "a%3Ab%2Cc" {
+		t.Errorf("escapeProperty = %q", got)
+	}
+}