harness

package
v1.0.4 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: May 26, 2026 License: Apache-2.0 Imports: 28 Imported by: 0

Documentation

Overview

Package harness provides a test harness for integration testing the STS token exchange: mock GitHub and OIDC servers, HTTP client, and helpers to build contexts and run exchanges.

Index

Constants

View Source 
const (
	// DefaultRepo is the default target repository for harness tests.
	DefaultRepo = "example-org/example-repo"
	// DefaultInstallationID is the default GitHub App installation ID used in mock responses.
	DefaultInstallationID = int64(123456)
	// DefaultPolicyTemplate is the default trust policy fixture name under fixtures/policies.
	DefaultPolicyTemplate = "contents_read_metadata_read.tpl.yaml"
)

Variables

This section is empty.

Functions

This section is empty.

Types

type Client 

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

Client is an HTTP client for the STS token exchange API. It wraps HTTP communication and provides typed request/response handling.

func (*Client) Exchange 

func (c *Client) Exchange(ctx context.Context, req *ExchangeRequest) (*Result, error)

Exchange performs a token exchange request.

type Context 

type Context struct {
	GitHub *GitHub
	OIDC   *testutil.OIDCServer
	Client *Client
	// contains filtered or unexported fields
}

Context holds test state and provides methods for test execution. Cleanup is registered automatically via t.Cleanup — callers never need to call Close or Cleanup manually.

func New 

func New(t *testing.T) *Context

New creates a new test Context with mock servers initialized. Cleanup is automatic via t.Cleanup.

func (*Context) ClaimsWith 

func (c *Context) ClaimsWith(overrides map[string]any) map[string]any

ClaimsWith returns DefaultClaims with the given overrides merged in.

func (*Context) DefaultClaims 

func (c *Context) DefaultClaims() map[string]any

DefaultClaims returns standard OIDC claims for the context (iss, sub, aud, exp, repository, ref, etc.).

func (*Context) DefaultToken 

func (c *Context) DefaultToken() string

DefaultToken returns a signed OIDC token with DefaultClaims.

func (*Context) ExchangeDefault 

func (c *Context) ExchangeDefault() (*Result, error)

ExchangeDefault performs an exchange request with DefaultToken and DefaultRepo.

func (*Context) FixturePath 

func (c *Context) FixturePath(parts ...string) string

FixturePath returns the path to a fixture file under the test fixtures directory (relative to cwd).

func (*Context) GitHubAPIURL 

func (c *Context) GitHubAPIURL() string

GitHubAPIURL returns the mock GitHub API base URL.

func (*Context) IssuerURL 

func (c *Context) IssuerURL() string

IssuerURL returns the OIDC issuer URL for the test context.

func (*Context) LoadTemplate 

func (c *Context) LoadTemplate(parts ...string) string

LoadTemplate reads a fixture file under fixtures/ and substitutes {{ISSUER_URL}} with the context issuer URL.

func (*Context) SetupDefaultPolicy 

func (c *Context) SetupDefaultPolicy()

SetupDefaultPolicy calls SetupPolicy with DefaultRepo and DefaultPolicyTemplate.

func (*Context) SetupPolicy 

func (c *Context) SetupPolicy(repo, template string)

SetupPolicy sets the trust policy and installation ID for the given repo using the named template fixture.

func (*Context) SignTokenWithClaims 

func (c *Context) SignTokenWithClaims(claims map[string]any) string

SignTokenWithClaims returns a signed OIDC token with the given claims.

func (*Context) TokenWith 

func (c *Context) TokenWith(overrides map[string]any) string

TokenWith returns a signed OIDC token with DefaultClaims merged with overrides.

type ExchangeRequest 

type ExchangeRequest struct {
	OIDCToken            string            `json:"oidc_token"`
	TargetRepository     string            `json:"target_repository"`
	PolicyName           string            `json:"policy_name,omitempty"`
	RequestedPermissions map[string]string `json:"requested_permissions,omitempty"`
	RequestedTTL         int               `json:"requested_ttl,omitempty"`
}

ExchangeRequest represents a token exchange request.

type ExchangeResponse 

type ExchangeResponse struct {
	Token         string            `json:"token"`
	ExpiresAt     time.Time         `json:"expires_at"`
	MatchedPolicy string            `json:"matched_policy"`
	Permissions   map[string]string `json:"permissions"`
	RequestID     string            `json:"request_id"`
}

ExchangeResponse represents a successful token exchange response.

type GitHub 

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

GitHub is a mock GitHub API server for testing. It supports policy file serving, installation lookup, and token creation.

func (*GitHub) APIURL 

func (g *GitHub) APIURL() string

APIURL returns the base URL of the mock GitHub API server. Use this URL to configure the STS service to use the mock GitHub.

func (*GitHub) Close 

func (g *GitHub) Close()

Close shuts down the mock server and releases all resources. This method is safe to call multiple times.

func (*GitHub) RequestCount 

func (g *GitHub) RequestCount() int

RequestCount returns the total number of requests received by the mock server.

func (*GitHub) SetError 

func (g *GitHub) SetError(pattern string, status int, message string)

SetError configures an error response for a path pattern. The pattern matches if the request path contains the pattern string.

func (*GitHub) SetInstallation 

func (g *GitHub) SetInstallation(repo string, id int64)

SetInstallation configures the installation ID for a repository.

func (*GitHub) SetLatency 

func (g *GitHub) SetLatency(d time.Duration)

SetLatency configures simulated network latency for all requests. This is useful for testing timeout behavior and slow network conditions.

func (*GitHub) SetPolicy 

func (g *GitHub) SetPolicy(repo, content string)

SetPolicy configures a policy file response for a repository.

func (*GitHub) SetPolicyFromFile 

func (g *GitHub) SetPolicyFromFile(repo, path string)

SetPolicyFromFile loads a policy from a fixture file.

func (*GitHub) SetRateLimit 

func (g *GitHub) SetRateLimit(pattern string, retryAfter int)

SetRateLimit configures a rate limit error for a path pattern. The rate limit response includes a Retry-After header with the specified value.

func (*GitHub) SetToken 

func (g *GitHub) SetToken(id int64, value string, permissions map[string]string, expiresAt time.Time)

SetToken configures the token response for an installation.

func (*GitHub) WasRequested 

func (g *GitHub) WasRequested(path string) bool

WasRequested checks if any request path contains the specified substring. Use this to verify that expected API endpoints were called.

type Request 

type Request struct {
	Method string
	Path   string
	Time   time.Time
}

Request represents a recorded HTTP request.

type ResponseError 

type ResponseError struct {
	Code              string `json:"error_code"`
	Message           string `json:"error"`
	Details           string `json:"details,omitempty"`
	RequestID         string `json:"request_id,omitempty"`
	RetryAfterSeconds int    `json:"retry_after_seconds,omitempty"`
}

ResponseError represents an error response from the STS API.

func (*ResponseError) Error 

func (e *ResponseError) Error() string

Error implements the error interface for ResponseError.

type Result 

type Result struct {
	Response   *ExchangeResponse
	Error      *ResponseError
	StatusCode int
}

Result wraps the outcome of an exchange request. Either Response or Error is set, never both.

type Server 

type Server struct {
	HTTP *httptest.Server
	// contains filtered or unexported fields
}

Server wraps the STS service and HTTP test server for integration testing.

func StartServer 

func StartServer(t *testing.T, ctx *Context, options ...ServerOption) *Server

StartServer creates and starts a new STS test server. Cleanup is registered via t.Cleanup — callers never need to call Close.

func (*Server) Close 

func (s *Server) Close()

Close shuts down the server and releases resources.

type ServerOption 

type ServerOption func(*serverConfig)

ServerOption configures the Server during creation.

func WithConfiguration 

func WithConfiguration(cfg *config.Config) ServerOption

WithConfiguration sets the full config for the test server; policy and OIDC are still overridden from Context.

func WithDefaultTTL 

func WithDefaultTTL(ttl int) ServerOption

WithDefaultTTL sets the default token TTL in seconds for the test server policy.

func WithGitHubApps 

func WithGitHubApps(apps []*TestApp) ServerOption

WithGitHubApps sets the GitHub Apps (client ID and org) used by the test server.

func WithMaxPermissions 

func WithMaxPermissions(permissions map[string]string) ServerOption

WithMaxPermissions sets the maximum allowed permissions for the test server policy.

func WithMaxTTL 

func WithMaxTTL(ttl int) ServerOption

WithMaxTTL sets the maximum token TTL in seconds for the test server policy.

func WithRequireExplicitPolicy 

func WithRequireExplicitPolicy(require bool) ServerOption

WithRequireExplicitPolicy sets whether the server requires an explicit repository policy to grant tokens.

type TestApp 

type TestApp struct {
	ClientID     string
	Organization string
}

TestApp describes a GitHub App for use in integration tests.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.