checktest

Documentation

Overview

Package checktest provides testing helpers when writing lint and breaking change plugins.

The easiest entry point is TestCase. This allows you to set up a test and run it extremely easily. Other functions provide lower-level primitives if TestCase doesn't meet your needs.

Index

• func AssertAnnotationsEqual(t *testing.T, expectedAnnotations []ExpectedAnnotation, ...)
• func RequireAnnotationsEqual(t *testing.T, expectedAnnotations []ExpectedAnnotation, ...)
• func SpecTest(t *testing.T, spec *check.Spec)
• type CheckTest
  • func (c CheckTest) Run(t *testing.T)
• type ExpectedAnnotation
  • func (ea ExpectedAnnotation) String() string
• type ExpectedFileLocation
  • func (el *ExpectedFileLocation) String() string
• type ProtoFileSpec
  • func (p *ProtoFileSpec) ToFileDescriptors(ctx context.Context) ([]descriptor.FileDescriptor, error)
• type RequestSpec
  • func (r *RequestSpec) ToRequest(ctx context.Context) (check.Request, error)

Functions

func AssertAnnotationsEqual

func AssertAnnotationsEqual(t *testing.T, expectedAnnotations []ExpectedAnnotation, actualAnnotations []check.Annotation)

AssertAnnotationsEqual asserts that the Annotations equal the expected Annotations.

func RequireAnnotationsEqual

func RequireAnnotationsEqual(t *testing.T, expectedAnnotations []ExpectedAnnotation, actualAnnotations []check.Annotation)

RequireAnnotationsEqual requires that the Annotations equal the expected Annotations.

func SpecTest

func SpecTest(t *testing.T, spec *check.Spec)

SpecTest tests your spec with check.ValidateSpec.

Almost every plugin should run a test with SpecTest.

func TestSpec(t *testing.T) {
  t.Parallel()
  checktest.SpecTest(t, yourSpec)
}

Types

type CheckTest

type CheckTest struct {
	// Request is the request spec to test.
	Request *RequestSpec
	// Spec is the Spec to test.
	//
	// Required.
	Spec *check.Spec
	// ExpectedAnnotations are the expected Annotations that should be returned.
	ExpectedAnnotations []ExpectedAnnotation
}

CheckTest is a single Check test to run against a Spec.

func (CheckTest) Run

func (c CheckTest) Run(t *testing.T)

Run runs the test.

This will:

• Build the Files and AgainstFiles.
• Create a new Request.
• Create a new Client based on the Spec.
• Call Check on the Client.
• Compare the resulting Annotations with the ExpectedAnnotations, failing if there is a mismatch.

type ExpectedAnnotation

type ExpectedAnnotation struct {
	// RuleID is the ID of the Rule.
	//
	// Required.
	RuleID string
	// Message is the message returned from the annoation.
	//
	// If Message is not set on ExpectedAnnotation, this field will *not* be compared
	// against the value in Annotation. That is, it is valid to have an Annotation return
	// a message but to not set it on ExpectedAnnotation.
	Message string
	// FileLocation is the location of the failure.
	FileLocation *ExpectedFileLocation
	// AgainstFileLocation is the against location of the failure.
	AgainstFileLocation *ExpectedFileLocation
}

ExpectedAnnotation contains the values expected from an Annotation.

func (ExpectedAnnotation) String

func (ea ExpectedAnnotation) String() string

String implements fmt.Stringer.

type ExpectedFileLocation

type ExpectedFileLocation struct {
	// FileName is the name of the file.
	FileName string
	// StartLine is the zero-indexed start line.
	StartLine int
	// StartColumn is the zero-indexed start column.
	StartColumn int
	// EndLine is the zero-indexed end line.
	EndLine int
	// EndColumn is the zero-indexed end column.
	EndColumn int
}

ExpectedFileLocation contains the values expected from a Location.

func (*ExpectedFileLocation) String

func (el *ExpectedFileLocation) String() string

String implements fmt.Stringer.

type ProtoFileSpec

type ProtoFileSpec struct {
	// DirPaths are the paths where .proto files are contained.
	//
	// Imports within .proto files should derive from one of these directories.
	// This must contain at least one element.
	//
	// This corresponds to the -I flag in protoc.
	DirPaths []string
	// FilePaths are the specific paths to build within the DirPaths.
	//
	// Any imports of the FilePaths will be built as well, and marked as imports.
	// This must contain at least one element.
	// Paths should be relative to DirPaths.
	//
	// This corresponds to arguments passed to protoc.
	FilePaths []string
}

ProtoFileSpec specifies files to be compiled for testing.

This allows tests to effectively point at a directory, and get back a *descriptorpb.FileDesriptorSet, or more to the point, check.Files that can be passed on a Request.

func (*ProtoFileSpec) ToFileDescriptors

func (p *ProtoFileSpec) ToFileDescriptors(ctx context.Context) ([]descriptor.FileDescriptor, error)

ToFileDescriptors compiles the files into descriptor.FileDescriptors.

If p is nil, this returns an empty slice.

type RequestSpec

type RequestSpec struct {
	// Files specifies the input files to test against.
	//
	// Required.
	Files *ProtoFileSpec
	// AgainstFiles specifies the input against files to test against, if anoy.
	AgainstFiles *ProtoFileSpec
	// RuleIDs are the specific RuleIDs to run.
	RuleIDs []string
	// Options are any options to pass to the plugin.
	Options map[string]any
}

RequestSpec specifies request parameters to be compiled for testing.

This allows a Request to be built from a directory of .proto files.

func (*RequestSpec) ToRequest

func (r *RequestSpec) ToRequest(ctx context.Context) (check.Request, error)

ToRequest converts the spec into a check.Request.

If r is nil, this returns nil.