Skip to content

Commit

Permalink
Resolves #3088: version sub-command expected behaviour documentatio…
Browse files Browse the repository at this point in the history
…n and testing (#3447)

* expected behaviour docs of the command sub-version

partially addresses #3088

Signed-off-by: Omri Bornstein <[email protected]>

* initial version stdout testing

Signed-off-by: Omri Bornstein <[email protected]>

* more verbose version stdout test

Signed-off-by: Omri Bornstein <[email protected]>

* resolves comments of PR 3447

Signed-off-by: Omri Bornstein <[email protected]>

* moved version docs to root level md file

Signed-off-by: Omri Bornstein <[email protected]>

* added missing new line in CLI.md

Signed-off-by: Omri Bornstein <[email protected]>

* golangci linting fix

Signed-off-by: Omri Bornstein <[email protected]>

---------

Signed-off-by: Omri Bornstein <[email protected]>
  • Loading branch information
AppleGamer22 authored Dec 20, 2023
1 parent 7763aef commit b3af55c
Show file tree
Hide file tree
Showing 2 changed files with 137 additions and 0 deletions.
41 changes: 41 additions & 0 deletions CLI.md
Original file line number Diff line number Diff line change
Expand Up @@ -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"
}
```
96 changes: 96 additions & 0 deletions cmd/cosign/cli/version_test.go
Original file line number Diff line number Diff line change
@@ -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)
}

0 comments on commit b3af55c

Please sign in to comment.