Merge pull request #17 from jaypipes/jaypipes/depends

improve dependency version constraint and errors

Author: jaypipes

README.md

@@ -26,17 +26,26 @@ All `gdt` scenarios have the following fields:
 * `fixtures`: (optional) list of strings indicating named fixtures that will be
   started before any of the tests in the file are run
 * `depends`: (optional) list of [`Dependency`][dependency] objects that
-  describe a program or package that should be available in the host's `PATH`
+  describe a program binary that should be available in the host's `PATH`
   that the test scenario depends on.
-* `depends.name`: string name of the program or package the test scenario
-  depends on.
+* `depends.name`: string name of the program the test scenario depends on.
 * `depends.when`: (optional) object describing any constraints/conditions that
   should apply to the evaluation of the dependency.
 * `depends.when.os`: (optional) string operating system. if set, the dependency
   is only checked for that OS.
-* `depends.when.version`: (optional) string version constraint. if set, the
+* `depends.version`: (optional) struct containing version constraint and
+  selector instructions.
+* `depends.version.constraint`: optional string version constraint. if set, the
   program or package must be available on the host `PATH` and must satisfy the
   version constraint.
+* `depends.version.selector`: (optional) struct containing selector
+  instructions for gdt to determine the version of a dependent binary.
+* `depends.version.selector.args`: (optional) set of string arguments to call
+  the dependency binary with in order to get the program's version information.
+  If empty, we default to []string{`-v`}.
+* `depends.version.selector.filter`: (optional) regular expression to run
+  against the returned output from executing the dependency binary with the
+  `selector.args` arguments. If empty, we use a loose semver matching regex.
 * `skip-if`: (optional) list of [`Spec`][basespec] specializations that will be
   evaluated *before* running any test in the scenario. If any of these
   conditions evaluates successfully, the test scenario will be skipped.
@@ -249,6 +258,54 @@ $ gdt run myapp.yaml
 Error: runtime error: exec: "myapp": executable file not found in $PATH
 ```
 
+You may also specify a particular version constraint that must pass for a
+dependent binary with the `depends.version.constraint` field. For example,
+let's assume I want to declare my test scenario requires that at least version
+`1.2.3` of `myapp` must be present on the host machine, I would do this:
+
+```yaml
+depends:
+ - name: myapp
+   version:
+     constraint: ">=1.2.3"
+```
+
+The `depends.version.constraint` field should be a valid Semantic Versioning
+constraint. Read more about [Semantic Version constraints][semver-constraints].
+
+By default to determine a binary's version, we pass a `-v` flag to the binary
+itself. If you know that a binary uses a different way of returning its version
+information, you can use the `depends.version.selector.args` field. As an
+example, the `ls` command line utility on Linux returns its version information
+when you pass the `--version` CLI flag, as shown here:
+
+```
+> ls --version
+ls (GNU coreutils) 9.4
+Copyright (C) 2023 Free Software Foundation, Inc.
+License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>.
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+
+Written by Richard M. Stallman and David MacKenzie.
+```
+
+If you wanted to require that, say, version 9.1 and later of the `ls`
+command-line utility was present on the host machine, you would do the
+following:
+
+```yaml
+depends:
+ - name: ls
+   version:
+     constraint: ">=9.1"
+     selector:
+       args:
+        - "--version"
+```
+
+[semver-constraints]: https://github.com/Masterminds/semver/blob/master/README.md#checking-version-constraints
+
 ### Passing variables to subsequent test specs
 
 A `gdt` test scenario is comprised of a list of test specs. These test specs

api/dependency.go

@@ -1,23 +1,220 @@
 package api
 
-// Dependency describes a prerequisite binary or package that must be present.
+import (
+	"regexp"
+
+	"github.com/Masterminds/semver/v3"
+	"github.com/samber/lo"
+	"gopkg.in/yaml.v3"
+
+	"github.com/gdt-dev/core/parse"
+)
+
+var (
+	ValidOSs = []string{
+		"linux",
+		"darwin",
+		"windows",
+	}
+)
+
+// Dependency describes a prerequisite binary that must be present.
 type Dependency struct {
-	// Name is the name of the binary or package
+	// Name is the name of the binary that must be present.
 	Name string `yaml:"name"`
 	// When describes any constraining conditions that apply to this
 	// Dependency.
-	When *DependencyConstraints `yaml:"when,omitempty"`
+	When *DependencyConditions `yaml:"when,omitempty"`
+	// Version contains instructions for constraining and selecting the
+	// dependency's version.
+	Version *DependencyVersion `yaml:"version,omitempty"`
 }
 
-// DependencyConstraints describes constraining conditions that apply to a
+func (d *Dependency) UnmarshalYAML(node *yaml.Node) error {
+	if node.Kind != yaml.MappingNode {
+		return parse.ExpectedMapAt(node)
+	}
+	for i := 0; i < len(node.Content); i += 2 {
+		keyNode := node.Content[i]
+		if keyNode.Kind != yaml.ScalarNode {
+			return parse.ExpectedScalarAt(keyNode)
+		}
+		key := keyNode.Value
+		valNode := node.Content[i+1]
+		switch key {
+		case "name":
+			if valNode.Kind != yaml.ScalarNode {
+				return parse.ExpectedScalarAt(valNode)
+			}
+			d.Name = valNode.Value
+		case "when":
+			if valNode.Kind != yaml.MappingNode {
+				return parse.ExpectedMapAt(valNode)
+			}
+			var when DependencyConditions
+			if err := valNode.Decode(&when); err != nil {
+				return err
+			}
+			d.When = &when
+		case "version":
+			if valNode.Kind != yaml.MappingNode {
+				return parse.ExpectedMapAt(valNode)
+			}
+			var dv DependencyVersion
+			if err := valNode.Decode(&dv); err != nil {
+				return err
+			}
+			d.Version = &dv
+		default:
+			return parse.UnknownFieldAt(key, keyNode)
+		}
+	}
+	return nil
+}
+
+// DependencyConditions describes constraining conditions that apply to a
 // Dependency, for instance whether the dependency is only required on a
-// particular OS or whether a particular version constraint applies to the
-// dependency.
-type DependencyConstraints struct {
+// particular OS.
+type DependencyConditions struct {
 	// OS indicates that the dependency only applies when the tests are run on
 	// a particular operating system.
 	OS string `yaml:"os,omitempty"`
-	// Version indicates a version constraint to apply to the dependency, e.g.
-	// >= 1.2.3
-	Version string `yaml:"version,omitempty"`
+}
+
+func (c *DependencyConditions) UnmarshalYAML(node *yaml.Node) error {
+	if node.Kind != yaml.MappingNode {
+		return parse.ExpectedMapAt(node)
+	}
+	for i := 0; i < len(node.Content); i += 2 {
+		keyNode := node.Content[i]
+		if keyNode.Kind != yaml.ScalarNode {
+			return parse.ExpectedScalarAt(keyNode)
+		}
+		key := keyNode.Value
+		valNode := node.Content[i+1]
+		switch key {
+		case "os":
+			if valNode.Kind != yaml.ScalarNode {
+				return parse.ExpectedScalarAt(valNode)
+			}
+			os := valNode.Value
+			if os != "" {
+				if !lo.Contains(ValidOSs, os) {
+					return parse.InvalidOSAt(valNode, os, ValidOSs)
+				}
+				c.OS = os
+			}
+		default:
+			return parse.UnknownFieldAt(key, keyNode)
+		}
+	}
+	return nil
+}
+
+// DependencyVersion expresses a version constraint that must be met for a
+// particular dependency and instructs gdt how to get the version for a
+// dependency from a binary or package manager.
+type DependencyVersion struct {
+	// Constraint indicates a version constraint to apply to the dependency,
+	// e.g.  '>= 1.2.3' would indicate that a version of the dependency binary
+	// after and including 1.2.3 must be present on the host.
+	Constraint        string              `yaml:"constraint"`
+	SemVerConstraints *semver.Constraints `yaml:"-"`
+	// Selector provides instructions to select the version from the binary.
+	Selector *DependencyVersionSelector `yaml:"selector,omitempty"`
+}
+
+func (v *DependencyVersion) UnmarshalYAML(node *yaml.Node) error {
+	if node.Kind != yaml.MappingNode {
+		return parse.ExpectedMapAt(node)
+	}
+	for i := 0; i < len(node.Content); i += 2 {
+		keyNode := node.Content[i]
+		if keyNode.Kind != yaml.ScalarNode {
+			return parse.ExpectedScalarAt(keyNode)
+		}
+		key := keyNode.Value
+		valNode := node.Content[i+1]
+		switch key {
+		case "constraint":
+			if valNode.Kind != yaml.ScalarNode {
+				return parse.ExpectedScalarAt(valNode)
+			}
+			conStr := valNode.Value
+			if conStr != "" {
+				con, err := semver.NewConstraint(conStr)
+				if err != nil {
+					return parse.InvalidVersionConstraintAt(
+						valNode, conStr, err,
+					)
+				}
+				v.Constraint = conStr
+				v.SemVerConstraints = con
+			}
+		case "selector":
+			if valNode.Kind != yaml.MappingNode {
+				return parse.ExpectedMapAt(valNode)
+			}
+			var selector DependencyVersionSelector
+			if err := valNode.Decode(&selector); err != nil {
+				return err
+			}
+			v.Selector = &selector
+		default:
+			return parse.UnknownFieldAt(key, keyNode)
+		}
+	}
+	return nil
+}
+
+// DependencyVersionSelector instructs gdt how to get the version of a binary.
+type DependencyVersionSelector struct {
+	// Args is the command-line to execute the dependency binary to output
+	// version information, e.g. '-v' or '--version-json'.
+	Args []string `yaml:"args,omitempty"`
+	// Filter is an optional regex to run against the output returned by
+	// Command, e.g. 'v?(\d)+\.(\d+)(\.(\d)+)?'.
+	Filter      string         `yaml:"filter,omitempty"`
+	FilterRegex *regexp.Regexp `yaml:"-"`
+}
+
+func (s *DependencyVersionSelector) UnmarshalYAML(node *yaml.Node) error {
+	if node.Kind != yaml.MappingNode {
+		return parse.ExpectedMapAt(node)
+	}
+	for i := 0; i < len(node.Content); i += 2 {
+		keyNode := node.Content[i]
+		if keyNode.Kind != yaml.ScalarNode {
+			return parse.ExpectedScalarAt(keyNode)
+		}
+		key := keyNode.Value
+		valNode := node.Content[i+1]
+		switch key {
+		case "args":
+			if valNode.Kind != yaml.SequenceNode {
+				return parse.ExpectedSequenceAt(valNode)
+			}
+			var args []string
+			if err := valNode.Decode(&args); err != nil {
+				return err
+			}
+			s.Args = args
+		case "filter":
+			if valNode.Kind != yaml.ScalarNode {
+				return parse.ExpectedMapAt(valNode)
+			}
+			filter := valNode.Value
+			if filter != "" {
+				re, err := regexp.Compile(filter)
+				if err != nil {
+					return parse.InvalidRegexAt(valNode, filter, err)
+				}
+				s.Filter = filter
+				s.FilterRegex = re
+			}
+		default:
+			return parse.UnknownFieldAt(key, keyNode)
+		}
+	}
+	return nil
 }

api/error.go

@@ -147,19 +147,29 @@ var (
 // DependencyNotSatified returns an ErrDependencyNotSatisfied with the supplied
 // dependency name and optional constraints.
 func DependencyNotSatisfied(dep *Dependency) error {
-	constraintsStr := ""
-	constraints := []string{}
+	conditionsStr := ""
+	conditions := []string{}
 	progName := dep.Name
 	if dep.When != nil {
 		if dep.When.OS != "" {
-			constraints = append(constraints, "OS:"+dep.When.OS)
+			conditions = append(conditions, "OS:"+dep.When.OS)
 		}
-		if dep.When.Version != "" {
-			constraints = append(constraints, "VERSION:"+dep.When.Version)
-		}
-		constraintsStr = fmt.Sprintf(" (%s)", strings.Join(constraints, ","))
 	}
-	return fmt.Errorf("%w: %s%s", ErrDependencyNotSatisfied, progName, constraintsStr)
+	conditionsStr = fmt.Sprintf(" (%s)", strings.Join(conditions, ","))
+	return fmt.Errorf("%w: %s%s", ErrDependencyNotSatisfied, progName, conditionsStr)
+}
+
+// DependencyNotSatifiedVersionConstraint returns an ErrDependencyNotSatisfied with the supplied
+// dependency name and version constraint failure.
+func DependencyNotSatisfiedVersionConstraint(
+	dep *Dependency,
+	constraintStr string,
+) error {
+	progName := dep.Name
+	return fmt.Errorf(
+		"%w: %q failed version constraint %q",
+		ErrDependencyNotSatisfied, progName, constraintStr,
+	)
 }
 
 // RequiredFixtureMissing returns an ErrRequiredFixture with the supplied

go.mod

@@ -3,6 +3,7 @@ module github.com/gdt-dev/core
 go 1.24.3
 
 require (
+	github.com/Masterminds/semver/v3 v3.4.0
 	github.com/cenkalti/backoff v2.2.1+incompatible
 	github.com/google/shlex v0.0.0-20191202100458-e7afc7fbc510
 	github.com/google/uuid v1.6.0

go.sum

@@ -1,3 +1,5 @@
+github.com/Masterminds/semver/v3 v3.4.0 h1:Zog+i5UMtVoCU8oKka5P7i9q9HgrJeGzI9SA1Xbatp0=
+github.com/Masterminds/semver/v3 v3.4.0/go.mod h1:4V+yj/TJE1HU9XfppCwVMZq3I84lprf4nC11bSS5beM=
 github.com/cenkalti/backoff v2.2.1+incompatible h1:tNowT99t7UNflLxfYYSlKYsBpXdEet03Pg2g16Swow4=
 github.com/cenkalti/backoff v2.2.1+incompatible/go.mod h1:90ReRw6GdpyfrHakVjL/QHaoyV4aDUVVkXQJJJ3NXXM=
 github.com/creack/pty v1.1.9/go.mod h1:oKZEueFk5CKHvIhNR5MUki03XCEU+Q6VDXinZuGJ33E=