Resolves #3088: version sub-command expected behaviour documentation and testing

CLI.md

@@ -3,3 +3,44 @@
 * The *primary* output of any command should be to STDOUT. The format should be
   described in the documentation of each command.
 * Output to STDERR is informational only.
+
+# Expected `cosign version` Behaviour
+From version 2.1.0 (as part of a [dependency update](https://github.com/sigstore/cosign/commit/40dbbd8b09bd5c30191d6e7e7ced3bbd7f6ea559)), the version metadata is [printed to standard output](https://github.com/kubernetes-sigs/release-utils/pull/76). By default it includes the package version, commit hash, git tree state, build date, Go version, compiler toolchain and current platform.
+
+## ASCII Output
+The output of `cosign version` is expected to resemble this format, with the specific values being appropriate for each build of the `cosign` package.
+
+```
+$ cosign version
+  ______   ______        _______. __    _______ .__   __.
+ /      | /  __  \      /       ||  |  /  _____||  \ |  |
+|  ,----'|  |  |  |    |   (----`|  | |  |  __  |   \|  |
+|  |     |  |  |  |     \   \    |  | |  | |_ | |  . `  |
+|  `----.|  `--'  | .----)   |   |  | |  |__| | |  |\   |
+ \______| \______/  |_______/    |__|  \______| |__| \__|
+cosign: A tool for Container Signing, Verification and Storage in an OCI registry.
+
+GitVersion:    [vX.Y.Z or devel]
+GitCommit:     [hash or unknown]
+GitTreeState:  [clean or dirty]
+BuildDate:     [yyyy-MM-ddThh:mm:ss or unknown]
+GoVersion:     go1.A.B
+Compiler:      gc
+Platform:      os/arch
+```
+
+## JSON Output
+The output of `cosign version --json` is expected to resemble this format, with the specific values being appropriate for each build of the `cosign` package.
+
+```
+$ cosign version --json
+{
+  "gitVersion": "[vX.Y.Z or devel]",
+  "gitCommit": "[hash or unknown]",
+  "gitTreeState": "[clean or dirty]",
+  "buildDate": "[yyyy-MM-ddThh:mm:ss or unknown]",
+  "goVersion": "go1.A.B",
+  "compiler": "gc",
+  "platform": "os/arch"
+}
+```

cmd/cosign/cli/version_test.go

@@ -0,0 +1,96 @@
+// Copyright 2023 The Sigstore 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 cli
+
+import (
+	"bytes"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"io"
+	"os"
+	"regexp"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"sigs.k8s.io/release-utils/version"
+)
+
+var (
+	expectedVersionInfo = version.GetVersionInfo()
+	reGitVersion        = regexp.MustCompile(fmt.Sprintf("\nGitVersion:\\s+%s\n", expectedVersionInfo.GitVersion))
+	reGitCommmit        = regexp.MustCompile(fmt.Sprintf("GitCommit:\\s+%s\n", expectedVersionInfo.GitCommit))
+	reBuildDate         = regexp.MustCompile(fmt.Sprintf("BuildDate:\\s+%s\n", expectedVersionInfo.BuildDate))
+	reGoVersion         = regexp.MustCompile(fmt.Sprintf("GoVersion:\\s+%s\n", expectedVersionInfo.GoVersion))
+	reCompiler          = regexp.MustCompile(fmt.Sprintf("Compiler:\\s+%s\n", expectedVersionInfo.Compiler))
+	rePlatform          = regexp.MustCompile(fmt.Sprintf("Platform:\\s+%s\n", expectedVersionInfo.Platform))
+)
+
+func getVersionSTDOUT(json bool) (bytes.Buffer, error) {
+	command := New()
+	if json {
+		command.SetArgs([]string{"version", "--json"})
+	} else {
+		command.SetArgs([]string{"version"})
+	}
+	// testing approach inspired by https://github.com/zenizh/go-capturer/blob/master/main.go
+	reader, writer, err := os.Pipe()
+	if err != nil {
+		return bytes.Buffer{}, errors.New("failed to create a pipe for testing os.Stdout")
+	}
+	stdout := os.Stdout
+	os.Stdout = writer
+	err = command.Execute()
+	os.Stdout = stdout
+	if err != nil {
+		return bytes.Buffer{}, errors.New("version is expected to run with a")
+	}
+	writer.Close()
+
+	var buffer bytes.Buffer
+	_, err = io.Copy(&buffer, reader)
+	return buffer, err
+}
+
+func testVersionASCII(t *testing.T) {
+	buffer, err := getVersionSTDOUT(false)
+	output := buffer.String()
+	assert.NoError(t, err)
+	assert.Regexp(t, reGitVersion, output, "output doesn't contain the Git version tag")
+	assert.Regexp(t, reGitCommmit, output, "output doesn't contain the Git commit hash")
+	assert.Regexp(t, reBuildDate, output, "output doesn't contain the build date")
+	assert.Regexp(t, reGoVersion, output, "output doesn't contain the Go version")
+	assert.Regexp(t, reCompiler, output, "output doesn't contain the compiler name")
+	assert.Regexp(t, rePlatform, output, "output doesn't contain the platform name")
+}
+
+func testVersionJSON(t *testing.T) {
+	buffer, err := getVersionSTDOUT(true)
+	assert.NoError(t, err)
+	output := buffer.Bytes()
+	var actualVersionInfo version.Info
+	err = json.Unmarshal(output, &actualVersionInfo)
+	assert.NoError(t, err)
+	assert.Equal(t, expectedVersionInfo.GitVersion, actualVersionInfo.GitVersion)
+	assert.Equal(t, expectedVersionInfo.GitCommit, actualVersionInfo.GitCommit)
+	assert.Equal(t, expectedVersionInfo.BuildDate, actualVersionInfo.BuildDate)
+	assert.Equal(t, expectedVersionInfo.GoVersion, actualVersionInfo.GoVersion)
+	assert.Equal(t, expectedVersionInfo.Compiler, actualVersionInfo.Compiler)
+	assert.Equal(t, expectedVersionInfo.Platform, actualVersionInfo.Platform)
+}
+
+func TestVersionOutput(t *testing.T) {
+	t.Run("ASCII", testVersionASCII)
+	t.Run("JSON", testVersionJSON)
+}