servertest

Documentation

Overview

Package servertest contains helpers for running server integration tests.

This package needs a lot more work. It is basically a placeholder now with a single test that makes sure OpenTelemetry stuff can start (since it broke in production before). The API is not final.

Index

• Constants
• type FakeRPCAuth
  • func (r *FakeRPCAuth) Authenticate(ctx context.Context, md auth.RequestMetadata) (*auth.User, auth.Session, error)
• type FakeRPCTokenGenerator
  • func (g *FakeRPCTokenGenerator) GenerateIDToken(ctx context.Context, audience string, _ time.Duration) (*oauth2.Token, error)
  • func (g *FakeRPCTokenGenerator) GenerateOAuthToken(ctx context.Context, scopes []string, _ time.Duration) (*oauth2.Token, error)
  • func (g *FakeRPCTokenGenerator) GetEmail() (string, error)
• type FakeToken
  • func GetFakeToken(ctx context.Context) *FakeToken
• type Settings
• type TestServer
  • func RunServer(ctx context.Context, settings *Settings) (*TestServer, error)
  • func (ts *TestServer) Context() context.Context
  • func (ts *TestServer) FakeClientRPCAuth() *lucictx.LocalAuth
  • func (ts *TestServer) GRPCAddr() string
  • func (ts *TestServer) GRPCConn(opts ...grpc.DialOption) (*grpc.ClientConn, error)
  • func (ts *TestServer) HTTPAddr() string
  • func (ts *TestServer) Shutdown()

Constants

const FakeClientIdentity identity.Identity = "user:client@servertest.example.com"

FakeClientIdentity is how clients authenticate as by default when using fake RPC client auth.

See DisableFakeClientRPCAuth in Settings for details.

Types

type FakeRPCAuth

type FakeRPCAuth struct {
	// Seed is a random value expected to be found inside fake tokens.
	//
	// Each local server under test has its own seed. This is a precaution against
	// unrelated tests unexpectedly cross-talking to one another.
	Seed uint64

	// IDTokensAudience is ID token audiences to accept as valid.
	//
	// This normally includes "http[s]://127.0.0.1:<port>" addresses of the local
	// server, but may also include any other audiences passed via Options.
	//
	// If empty, ID tokens won't be accepted at all.
	IDTokensAudience stringset.Set
}

FakeRPCAuth implements auth.Method by accepting fake tokens as generated by FakeRPCTokenGenerator.

It is used to authenticate incoming calls.

func (*FakeRPCAuth) Authenticate

func (r *FakeRPCAuth) Authenticate(ctx context.Context, md auth.RequestMetadata) (*auth.User, auth.Session, error)

Authenticate is part of auth.Method interface.

type FakeRPCTokenGenerator

type FakeRPCTokenGenerator struct {
	// Seed is a random value to put into fake tokens.
	//
	// Each local server under test has its own seed. This is a precaution against
	// unrelated tests unexpectedly cross-talking to one another.
	Seed uint64

	// Email to put into fake tokens.
	//
	// It will show up as an authenticated user email on the server side.
	Email string
}

FakeRPCTokenGenerator knows how to produce tokens understood by FakeRPCAuth.

Implements localauth.TokenGenerator.

func (*FakeRPCTokenGenerator) GenerateIDToken

func (g *FakeRPCTokenGenerator) GenerateIDToken(ctx context.Context, audience string, _ time.Duration) (*oauth2.Token, error)

GenerateIDToken is part of localauth.TokenGenerator interface.

func (*FakeRPCTokenGenerator) GenerateOAuthToken

func (g *FakeRPCTokenGenerator) GenerateOAuthToken(ctx context.Context, scopes []string, _ time.Duration) (*oauth2.Token, error)

GenerateOAuthToken is part of localauth.TokenGenerator interface.

func (*FakeRPCTokenGenerator) GetEmail

func (g *FakeRPCTokenGenerator) GetEmail() (string, error)

GetEmail is part of localauth.TokenGenerator interface.

type FakeToken

type FakeToken struct {
	Kind   string   `json:"kind"`
	Email  string   `json:"email"`
	Expiry int64    `json:"expiry"`
	Seed   uint64   `json:"seed"`
	Aud    string   `json:"aud,omitempty"`
	Scopes []string `json:"scopes,omitempty"`
}

FakeToken is a payload of a fake RPC auth token.

func GetFakeToken

func GetFakeToken(ctx context.Context) *FakeToken

GetFakeToken returns an info about the fake token used to authenticate this call or nil if this call wasn't authenticated by a fake token.

type Settings

type Settings struct {
	// Options are base server options.
	//
	// In production they are usually parsed from flags, but here they should
	// be supplied explicitly (unless defaults are not good).
	//
	// Some of the fields will be forcefully overridden to make sure the server
	// behaves well in the test environment. In particular `Prod` will always be
	// false.
	//
	// If nil, some safe defaults will be used.
	Options *server.Options

	// Modules is a list of configured modules to use in the server.
	//
	// Unlike the production server, no flag parsing is done. Modules need to be
	// created using concrete options suitable for the test (i.e. do not use
	// NewModuleFromFlags, since there are no flags).
	Modules []module.Module

	// Init is called during the server initialization before starting it.
	//
	// This is a place where various routes can be registered and extra background
	// activities started.
	Init func(srv *server.Server) error

	// DisableFakeGCEMetadata can be used to **disable** fake GCE metadata server.
	//
	// The GCE metadata server is used to grab authentication tokens when the
	// server makes calls to other services.
	//
	// By default (when DisableFakeGCEMetadata is false), the test server is
	// launched in an environment with a fake GCE metadata server that returns
	// fake tokens. It means it won't be able to make any real calls to external
	// services (and also accidentally do something bad).
	//
	// Additionally this fake GCE metadata makes the server believe it runs in a
	// GCP environment even when running on a local workstation. This will make it
	// hit more production code paths, potentially uncovering bugs there.
	//
	// If DisableFakeGCEMetadata is true the test server will use whatever is
	// available in the execution environment or configured via Options. This
	// generally means it will use real authentication tokens.
	DisableFakeGCEMetadata bool

	// DisableFakeClientRPCAuth can be used to **disable** fake RPC auth tokens.
	//
	// By default (when this option is false), the server is configured to accept
	// fake per-RPC authentication tokens and reject real ones. Clients that make
	// authenticated calls will need to be configured to send such fake tokens.
	// This can be done by injecting lucictx.LocalAuth into the context, see
	// FakeClientRPCAuth().
	//
	// RPC calls made from clients that use FakeClientRPCAuth() will be
	// authenticated as coming from FakeClientIdentity.
	//
	// If DisableFakeClientRPCAuth is true the test server will accept only real
	// OAuth and/or OpenID tokens (depending on Options). It means the test
	// clients will also need to generate real tokens, which may require
	// configuring tests to run under some real service account.
	DisableFakeClientRPCAuth bool
}

Settings are parameters for launching a test server.

type TestServer

type TestServer struct {
	// contains filtered or unexported fields
}

TestServer represents a running server-under-test.

func RunServer

func RunServer(ctx context.Context, settings *Settings) (*TestServer, error)

RunServer launches a test server and runs it in background.

It initializes the server based on the settings, launches its serving loop in a background goroutine and waits for the health check to successfully pass before returning.

The caller can then make HTTP or gRPC requests to the server via the loopback address in TestServer.

The caller is responsible to shut the server down when done with it via a call to Shutdown.

The given context is used as the root context for the server (eventually inherited by everything under it). It can be a background context if nothing extra is needed.

Note that some server's dependencies (in particular OpenTelemetry) use global variables and thus running multiple services in the same process concurrently may result in flakiness.

func (*TestServer) Context

func (ts *TestServer) Context() context.Context

Context is the server's root context with all modules initialized.

func (*TestServer) FakeClientRPCAuth

func (ts *TestServer) FakeClientRPCAuth() *lucictx.LocalAuth

FakeClientRPCAuth can be used to inject a fake local auth token provider into the LUCI context.

It can be inserted into the client context using regular lucictx API:

ctx = lucictx.SetLocalAuth(ctx, srv.FakeClientRPCAuth())

Return nil if DisableFakeClientRPCAuth is true.

func (*TestServer) GRPCAddr

func (ts *TestServer) GRPCAddr() string

GRPCAddr is "127.0.0.1:<port>" of the server's gRPC port.

func (*TestServer) GRPCConn

func (ts *TestServer) GRPCConn(opts ...grpc.DialOption) (*grpc.ClientConn, error)

GRPCConn returns a gRPC client connection to the server's gRPC port.

func (*TestServer) HTTPAddr

func (ts *TestServer) HTTPAddr() string

HTTPAddr is "127.0.0.1:<port>" of the server's HTTP port.

func (*TestServer) Shutdown

func (ts *TestServer) Shutdown()

Shutdown closes the server waiting for it to fully terminate.