protoc-gen-go-aip-test

Generate test suites for protobuf services implementing standard AIP methods.

The generated test suites are based on guidance for standard methods, and experience from implementing these methods in practice. See Suites for a list of the generated tests.

Experimental: This plugin is experimental, and breaking changes with regard to the generated tests suites should be expected.

Usage

Step 1: Declare a service with AIP standard methods

service FreightService {
  // Get a shipper.
  // See: https://google.aip.dev/131 (Standard methods: Get).
  rpc GetShipper(GetShipperRequest) returns (Shipper) {
    option (google.api.http) = {
      get: "/v1/{name=shippers/*}"
    };
    option (google.api.method_signature) = "name";
  }

  // ...
}

Step 2: Install the generator

Download a prebuilt binary from releases and put it in your PATH.

The generator can also be built from source using Go.

Step 3: Generate test suites

Include the plugin in protoc invocation

protoc
  --go-aip-test_out=[OUTPUT DIR] \
  --go-aip-test_opt=module=[OUTPUT MODULE] \
  [.proto files ...]

This can also be done via a buf generate template. See buf.gen.yaml for an example.

Step 4: Run tests

There are two alternative ways of bootstrapping the tests.

Alternative 1:

Instantiate the generated test suites and call the methods you want to test.

package example

func Test_FreightService(t *testing.T) {
    t.Skip("this is just an example, the service is not implemented.")
    // setup server before test
    server := examplefreightv1.UnimplementedFreightServiceServer{}
    // setup test suite
    suite := examplefreightv1.FreightServiceTestSuite{
        T:      t,
        Server: server,
    }

    // run tests for each resource in the service
    ctx := context.Background()
    suite.TestShipper(ctx, examplefreightv1.ShipperTestSuiteConfig{
        // Create should return a resource which is valid to create, i.e.
        // all required fields set.
        Create: func() *examplefreightv1.Shipper {
            return &examplefreightv1.Shipper{
                DisplayName:    "Example shipper",
                BillingAccount: "billingAccounts/12345",
            }
        },
        // Update should return a resource which is valid to update, i.e.
        // all required fields set.
        Update: func() *examplefreightv1.Shipper {
            return &examplefreightv1.Shipper{
                DisplayName:    "Updated example shipper",
                BillingAccount: "billingAccounts/54321",
            }
        },
    })
}

Alternative 2:

Implement the generated configure provider interface (FreightServiceTestSuiteConfigProvider) and pass the implementation to TestServices to start the tests.

A benefit of using TestServices (over alternative 1) is that as new services or resources are added to the API the test code won't compile until the required inputs are also added (or explicitly ignored). This makes it harder to forget to add the test implementations for new services/resources.

package example

import "testing"

func Test_FreightService(t *testing.T) {
    // Even though no implementation exists, the tests will pass but be skipped.
    examplefreightv1.TestServices(t, &aipTests{})
}

type aipTests struct{}

var _ examplefreightv1.FreightServiceTestSuiteConfigProvider = &aipTests{}

func (a aipTests) FreightServiceShipper(_ *testing.T) *examplefreightv1.FreightServiceShipperTestSuiteConfig {
    // Returns nil to indicate that it's not ready to be tested.
    return nil
}

func (a aipTests) FreightServiceSite(_ *testing.T) *examplefreightv1.FreightServiceSiteTestSuiteConfig {
    // Returns nil to indicate that it's not ready to be tested.
    return nil
}

Skipping tests

There may be multiple reasons for an API to deviate from the guidance for standard methods (for examples see AIP-200). This plugin supports skipping individual or groups of tests using the Skip field generated for each test suite config.

Each test are compared, using strings.Contains, against a list of skipped test patterns. The full name of each test will follow the format [resource]/[method type]/[test_name].

Sample skips:

• "Get/invalid_name" skips the "invalid name" test for Get standard method.
• "Get" skips all tests for a Get standard method.

Suites

Create

Get

BatchGet

Update

List

Search

Delete