Skip to content

Quick start

Writing a simple sshd test

An initial set of tests can be derived from the system state by using the add or autoadd commands.

Let's write a simple sshd test using autoadd.

# Running it as root will allow it to also detect ports
$ sudo syver autoadd sshd

On spec filenames: syver looks for syver.yaml, syver.yml, goss.yaml and goss.yml, in that order, and writes to whichever it found. When none exist it creates syver.yaml. The goss-named files keep working indefinitely, so an existing goss.yaml needs no migration; syver.yaml is simply the preferred name for new work. Note this is the filename only. Inside the file the import key stays gossfile: (syverfile: is accepted as an input alias).

Generated syver.yaml:

port:
  tcp:22:
    listening: true
    ip:

    - 0.0.0.0
    pid:
    - 1234
  tcp6:22:
    listening: true
    ip:
    - '::'
    pid:
    - 1234
service:
  sshd:
    enabled: true
    running: true
user:
  sshd:
    exists: true
    uid: 74
    gid: 74
    groups:
    - sshd
    home: /var/empty/sshd
    shell: /sbin/nologin
group:
  sshd:
    exists: true
    gid: 74
process:
  sshd:
    running: true
    status:
    - sleep
    user:
    - root

Now that we have a test suite, we can:

  • Run it once
$ syver validate
...............

Total Duration: 0.021s # <- yeah, it's that fast..
Count: 15, Failed: 0
  • Edit it to use templates, and run with a vars file
syver --vars vars.yaml validate
  • keep running it until the system enters a valid state or we timeout
syver validate --retry-timeout 30s --sleep 1s
  • serve the tests as a health endpoint
$ syver serve &
$ curl localhost:8080/healthz

# JSON endpoint
$ syver serve --format json &
$ curl localhost:8080/healthz

# rspecish response via content negotiation
$ syver serve --format json &
$ curl -H "Accept: application/vnd.goss-rspecish" localhost:8080/healthz

Manually editing Syver files

Syver files can be manually edited to improve readability and expressiveness of tests.

A Json draft 7 schema in docs/schema.yaml makes it easier to edit simple syver.yaml / goss.yaml files in IDEs, providing usual coding assistance such as inline documentation, completion and static analysis. See #793 for screenshots.

For example, to configure the Json schema in JetBrains intellij IDEA, follow documented instructions, with arguments such as:

  • schema url=docs/schema.yaml (path from the repository root)
  • schema version=Json schema version 7
  • file path pattern=*/syver.yaml (add a second pattern for */goss.yaml if you still have goss-named specs)

In addition, Syver files can also be further manually edited (without yet full json support) to use:

A typo'd top-level key (writing prot: instead of port:, for example) no longer validates silently: syver logs a [WARN] for it, with a suggestion when it can make one. See Unknown top-level keys.

Some examples:

user:
  sshd:
    title: UID must be between 50-100, GID doesn't matter. home is flexible
    meta:
      desc: Ensure sshd is enabled and running since it's needed for system management
      sev: 5
    exists: true
    uid:
      # Validate that UID is between 50 and 100
      and:
        gt: 50
        lt: 100
    home:
      # Home can be any of the following
      or:

      - /var/empty/sshd
      - /var/run/sshd

package:
  kernel:
    installed: true
    versions:
      # Must have 3 kernels and none of them can be 4.4.0
      and:

      - have-len: 3
      - not:
          contain-element: 4.4.0

  # Loaded from --vars YAML/JSON file
  {{.Vars.package}}:
    installed: true

{{if eq .Env.OS "centos"}}
  # This test is only when $OS environment variable is set to "centos"
  libselinux:
    installed: true
{{end}}

Spec files with templates can still be validated through the Json schema after being rendered using the syver render command. See example below

$ cd docs
$ syver --vars ./vars.yaml render > rendered_syver.yaml
# proceed with json schema validation of rendered_syver.yaml in your favorite IDE
# or in one of the Json schema validator listed in https://json-schema.org/implementations.html
# The following example is for a Linux AMD64 host
$ curl -LO https://github.com/neilpa/yajsv/releases/download/v1.4.1/yajsv.linux.amd64
$ chmod a+x yajsv.linux.amd64
$ sudo mv yajsv.linux.amd64 /usr/sbin/yajsv

$ yajsv -s schema.yaml rendered_syver.yaml
rendered_syver.yaml: pass

Full list of available Json schema validators can be found in https://json-schema.org/implementations.html#validator-command%20line

Discovery and test dependencies

Run lightweight discovery checks before the main suite and use the results in templates, or declare depends-on to skip dependents when a prerequisite fails. See Discovery and Test dependencies.

# Pre-run discovery, then validate main gossfile (preferred)
syver validate -g goss.yml --discover discovery.yaml

# Or inline discovery: in the same gossfile
syver validate -g goss-inline.yml

# Export discovery results for external tooling (unchanged)
syver validate -g discovery.yaml --format discovery

These examples pass goss-named files because that is what the checked-in fixtures are called. goss.yaml and goss.yml are still accepted, and always will be. -g takes any path, and a spec found by name is resolved across all four of syver.yaml, syver.yml, goss.yaml, goss.yml.

Fixtures: integration-tests/syver/examples/discovery/