v1.37.0 Latest Latest

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

Go to latest
Published: May 10, 2024 License: MPL-2.0 Imports: 6 Imported by: 0



Package et stands for Encore Tests and provides a number of functions and tools for writing fully integrated test suites for Encore applications.



This section is empty.


This section is empty.


func EnableServiceInstanceIsolation added in v1.30.0

func EnableServiceInstanceIsolation()

EnableServiceInstanceIsolation will causes all Service singletons to be isolated to each test from this test and on any of its sub-tests. (Calling this in a TestMain has the impact of isolating all tests in the package.)

By default, Service singletons are shared across all tests and initialized on the first call to that service by any test, which results in faster tests as you are not re-initializing the service for each test, however if your service structs contain state that is not reset between tests, this can cause issues. In that case, you can call this function to isolate the services for the impacted tests.

func MockEndpoint added in v1.30.0

func MockEndpoint[T any](originalEndpoint T, mock T, opts ...MockOption)

MockEndpoint allows you to mock out an endpoint in your tests; Any calls made to the endpoint during this test or any of its sub-tests will be routed to the mock you provide.

Your mocked function must match the signature of the endpoint you are mocking.

For example, if you have an endpoint defined as:

//encore:api public
func MyAPI(ctx context.Context, req *MyAPIRequest) (*MyAPIResponse, error) {

You can mock it out in your test as:

et.MockEndpoint(mysvc.MyAPI, func(ctx context.Context, req *MyAPIRequest) (*MyAPIResponse, error) {

If you want to mock out a single endpoint method on a service, you can use the generated helper package function as the `originalEndpoint` argument to this function, however if you want to mock out more than one API method on a service, consider using MockService.

Note: if you use MockService to mock a service and then use this function to mock an endpoint on that service, the endpoint mock will take precedence over the service mock.

Setting the mock to nil will remove the endpoint mock.

func MockService added in v1.30.0

func MockService[T any](serviceName string, mock T, opts ...MockOption)

MockService allows you to mock out a service in your tests; Any calls made to the service during this test or any of its sub-tests will be routed to the mock you provide.

Your mock must implement the all the API methods of the service which are used during the test(s). If you do not implement a method, it will panic when that method is called.

If you want to ensure compile time safety, you can use the Interface type generated for the service, which will ensure that you implement all the methods. For example:

package svca

import (


func TestServiceA(t *testing.T) {
	et.MockService[svcb.Interface]("svcb", &myMockType{})

Setting the mock to nil will remove the service mock.

func NewTestDatabase added in v1.37.0

func NewTestDatabase(ctx context.Context, name stringLiteral) (_ *sqldb.Database, _ error)

NewTestDatabase creates a new, fresh database for the database with the given name. The database name must be a database known to Encore (via `sqldb.NewDatabase`), otherwise it reports an error.

The new database is cloned from a template database that has had all migrations applied to it, but excludes any of the changes applied to the given db.

The returned database is isolated to the current test and any sub-tests, and is automatically dropped at the end of the test, and any open connections are automatically closed.

The provided name must be a constant string literal (like "mydb").

func OverrideAuthInfo added in v1.10.1

func OverrideAuthInfo(uid auth.UID, data any)

OverrideAuthInfo overrides the auth information for the current request. Subsequent calls to auth.UserID and auth.Data() within the same request will return the given uid and data, and API calls made from the request will propagate the newly set user info.

Passing in an empty string as the uid results in unsetting the auth information, causing future API calls to behave as if there was no authenticated user.

If the application's auth handler returns custom auth data, two additional requirements exist. First, the data parameter passed to WithContext must be of the same type as the auth handler returns. Second, if the uid argument is not the empty string then data may not be nil. If these requirements are not met, API calls made with these options will not be made and will immediately return a client-side error.

OverrideAuthInfo is not safe for concurrent use with code that invokes auth.UserID or auth.Data() within the same request.

func SetCfg added in v1.9.0

func SetCfg[T any](cfg config.Value[T], newValue T)

SetCfg changes the value of cfg to newValue within the current test and any subtests. Other tests running will not be affected.

It does not support setting slices and panics if given a config value that is a slice.


type MockOption added in v1.34.3

type MockOption func(*mockOptions)

MockOption is a function that can be passed to MockEndpoint or MockService to configure the mocking behavior.

func RunMiddleware added in v1.34.3

func RunMiddleware(enabled bool) (_ MockOption)

RunMiddleware is a MockOption that sets whether to run the middleware chain prior to invoking the mock.

type TopicHelpers

type TopicHelpers[T any] interface {
	// PublishedMessages returns a slice of all messages published during this test on this topic.
	PublishedMessages() []T

TopicHelpers provides functions for interacting with the backing topic implementation during unit tests. It is designed to help test code that uses the pubsub.Topic

Note all functions on this TopicHelpers are scoped to the current test and will only impact and observe state from the current test

func Topic

func Topic[T any](topic *pubsub.Topic[T]) (_ TopicHelpers[T])

Topic returns a TopicHelper for the given topic.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL