check

Overview ¶

Package check provides validation helpers for ygnmi queries.

These helpers wrap the .Lookup() and .Watch()/.Await() methods of Ondatra's ygnmi structs, eliminating a great deal of boilerplate and allowing table-driven testing of paths of different types.

Overview ¶

This package provides a set of functions for creating Validator objects, each of which represents a check to be performed against some gNMI path. A Validator can then be invoked in several different ways to actually perform the check. Typical usage looks like this:

// Create a table of Validators.
validators := []check.Validator{
	check.Equal(ocpath.Some().Path().State(), someValue),
	check.Present(ocpath.Some().OtherPath().Config()),
	check.NotEqual(ocpath.Another().Path().State(), anotherValue),
}
// Check each one and report any failures.
for _, vd:= range validators {
	t.Run(vd.Path(), func(t *testing.T) {
		if err := vd.Check(gnmiClient); err != nil {
			// err will already look like e.g. "some/path/state: got 12, want 0"
			// so no further formatting is necessary here.
			t.Error(err)
		}
	})
}

Validator functions ¶

The most generic validation function is

check.Validate(query, validationFn func(Value[T]) error)

This Validator validates by running validationFn on the query's value and returning any resulting error.

check also provides a number of shorthands for common cases:

• check.Equal(query, want) checks that the query's value is want.
• check.NotEqual(query, wantNot) checks that the query has any value other than wantNot.
• check.Present(query) checks that the query has any value at all.
• check.NotPresent(query) checks that the query is unset.
• check.EqualOrNil(query, want) checks that the query's value is want OR that the query is unset.
• check.Predicate[T](query PathStruct[T], wantMsg string, predicate func(T) bool) checks that the value at query is present and satisfies the given predicate function; wantMsg is used in the resulting error if it fails.

These helpers all have prewritten validation functions that return sensible errors of the form "<path>: <got>, <want>", such as:

/system/some/path: got no value, want 12
/system/hostname: got "wrongname", want "node1" or nil
/some/other/path: got 100, want no value

Validating a Validator ¶

Given a Validator, there are several ways to test its condition:

• vd.Check(client) executes the query immediately, tests the result, and returns any error generated by the validation function.
• vd.Await(ctx, client) will watch the specified path and return nil as soon as the validation passes; if this never happens, it will continue blocking until the context expires or is canceled.
• vd.AwaitUntil(deadline, client) is almost the same as creating a context with the given deadline and calling Await(), except that if the deadline is in the past it will call Check() instead.
• vd.AwaitFor(timeout, client) is AwaitUntil(time.Now().Add(timeout), client)

Accommodating latency ¶

There will often be some small latency between when a configuration variable is set via gNMI and when the corresponding operational state reflects the change. As a result, it's common to want to test several values with the expectation that all of them will be correct within some short window of time. The preferred way to do this is:

deadline := time.Now().Add(time.Second())
for _, vd:= range[]check.Validator {
	check.Equal(root.Some().Path(), someValue),
	check.Present(root.Some().OtherPath()),
	...
	check.NotEqual(root.Another().Path(), anotherValue),
} {
	t.Run(vd.Path(), func(t *testing.T) {
		if err := vd.AwaitUntil(deadline, client); err != nil {
			t.Error(err)
		}
	})
}

The above code expects that every validation will pass within one second of the start of the block. Don't use AwaitFor this, or else on a failing device the test could wait one second *per validator* instead of total.

Note that the above is also preferable to

ctx, _ := context.WithTimeout(context.Background(), time.Second())
for _, vd:= range[]check.Validator {
	...
} {
	t.Run(vd.Path(), func(t *testing.T) {
		if err := vd.Await(ctx, client); err != nil {
			t.Error(err)
		}
	})
}

This is because if the first validator times out, the other validators won't run because Await(ctx, client) aborts if the ctx has already expired, whereas AwaitUntil and AwaitFor will both be equivalent to Check if given a 0 or negative timeout or a deadline in the past.

Error Messages ¶

The error messages generated by failing checks will include the path, the value at that path, and a description of what the validator wanted, e.g.

some/path: got 12, want 19