keeper

README

Keeper Testing

The keeper package exposes an easy API for generating a set of "test keepers" and "test message servers" for performing integration testing on your application at the keeper level. Typical Cosmos SDK unit tests may use mocked keepers, or not use a full set that is representative of the full application.

This setup allows developers to test all keepers in coordination without having to spin up a local network or full application.

The framework initializes and returns keepers for the following modules:

• x/bank
• x/auth
• x/staking
• x/distribution
• x/feegrant
• x/mint

and is easily extendable to add any other keepers that you may with to test upon setup.

A typical testing flow that extends adds the Skip FeeMarket module might look like the following:

import (
	"testing"

	"github.com/cometbft/cometbft/libs/log"
	tmproto "github.com/cometbft/cometbft/proto/tendermint/types"
	storetypes "cosmossdk.io/store/types"
	sdk "github.com/cosmos/cosmos-sdk/types"
	authkeeper "github.com/cosmos/cosmos-sdk/x/auth/keeper"
	authtypes "github.com/cosmos/cosmos-sdk/x/auth/types"
	govtypes "github.com/cosmos/cosmos-sdk/x/gov/types"
	testkeeper "github.com/skip-mev/chaintestutil/keeper"
	"github.com/stretchr/testify/require"

	feemarketkeeper "github.com/skip-mev/feemarket/x/feemarket/keeper"
	feemarkettypes "github.com/skip-mev/feemarket/x/feemarket/types"
)

// TestKeepers holds all keepers used during keeper tests for all modules
type TestKeepers struct {
	testkeeper.TestKeepers
	FeeMarketKeeper *feemarketkeeper.Keeper
}

// TestMsgServers holds all message servers used during keeper tests for all modules
type TestMsgServers struct {
	testkeeper.TestMsgServers
	FeeMarketMsgServer feemarkettypes.MsgServer
}

var additionalMaccPerms = map[string][]string{
	feemarkettypes.ModuleName:       nil,
	feemarkettypes.FeeCollectorName: {authtypes.Burner},
}

// NewTestSetup returns initialized instances of all the keepers and message servers of the modules
func NewTestSetup(t testing.TB, options ...testkeeper.SetupOption) (sdk.Context, TestKeepers, TestMsgServers) {
	options = append(options, testkeeper.WithAdditionalModuleAccounts(additionalMaccPerms))

	_, tk, tms := testkeeper.NewTestSetup(t, options...)

	// initialize extra keeper
	feeMarketKeeper := FeeMarket(tk.Initializer, tk.AccountKeeper)
	require.NoError(t, tk.Initializer.LoadLatest())

	// initialize msg servers
	feeMarketMsgSrv := feemarketkeeper.NewMsgServer(*feeMarketKeeper)

	ctx := sdk.NewContext(tk.Initializer.StateStore, tmproto.Header{
		Time:   testkeeper.ExampleTimestamp,
		Height: testkeeper.ExampleHeight,
	}, false, log.NewNopLogger())

	err := feeMarketKeeper.SetState(ctx, feemarkettypes.DefaultState())
	require.NoError(t, err)
	err = feeMarketKeeper.SetParams(ctx, feemarkettypes.DefaultParams())
	require.NoError(t, err)

	testKeepers := TestKeepers{
		TestKeepers:     tk,
		FeeMarketKeeper: feeMarketKeeper,
	}

	testMsgServers := TestMsgServers{
		TestMsgServers:     tms,
		FeeMarketMsgServer: feeMarketMsgSrv,
	}

	return ctx, testKeepers, testMsgServers
}

// FeeMarket initializes the fee market module using the testkeepers intializer.
func FeeMarket(
	initializer *testkeeper.Initializer,
	authKeeper authkeeper.AccountKeeper,
) *feemarketkeeper.Keeper {
	storeKey := sdk.NewKVStoreKey(feemarkettypes.StoreKey)
	initializer.StateStore.MountStoreWithDB(storeKey, storetypes.StoreTypeIAVL, initializer.DB)

	return feemarketkeeper.NewKeeper(
		initializer.Codec,
		storeKey,
		authKeeper,
		authtypes.NewModuleAddress(govtypes.ModuleName).String(),
	)
}

Documentation

Overview

Package keeper provides methods to initialize SDK keepers with local storage for test purposes

Index

• Variables
• func ModuleAccountAddrs(maccPerms map[string][]string) map[string]bool
• func NewTestSetup(t testing.TB, options ...SetupOption) (sdk.Context, TestKeepers, TestMsgServers)
• type Initializer
  • func (i *Initializer) Auth(maccPerms map[string][]string) authkeeper.AccountKeeper
  • func (i *Initializer) Bank(authKeeper authkeeper.AccountKeeper, maccPerms map[string][]string) bankkeeper.Keeper
  • func (i *Initializer) Distribution(authKeeper authkeeper.AccountKeeper, bankKeeper bankkeeper.Keeper, ...) distrkeeper.Keeper
  • func (i *Initializer) FeeGrant(authKeeper authkeeper.AccountKeeper) feegrantkeeper.Keeper
  • func (i *Initializer) LoadLatest() error
  • func (i *Initializer) Staking(authKeeper authkeeper.AccountKeeper, bankKeeper bankkeeper.Keeper) *stakingkeeper.Keeper
  • func (i *Initializer) Upgrade() *upgradekeeper.Keeper
• type ProtocolVersionSetter
  • func (vs ProtocolVersionSetter) SetProtocolVersion(uint64)
• type SetupOption
  • func WithAdditionalModuleAccounts(maccPerms map[string][]string) SetupOption
• type SetupOptions
• type TestKeepers
  • func (tk *TestKeepers) MintToAccount(ctx sdk.Context, address string, coins sdk.Coins)
  • func (tk *TestKeepers) MintToModule(ctx sdk.Context, moduleAcc string, coins sdk.Coins)
• type TestMsgServers

Variables

var (
	// ExampleTimestamp is a timestamp used as the current time for the context of the keepers returned from the package
	ExampleTimestamp = time.Date(2020, time.January, 1, 12, 0, 0, 0, time.UTC)

	// ExampleHeight is a block height used as the current block height for the context of test keeper
	ExampleHeight = int64(1111)
)

Functions

func ModuleAccountAddrs

func ModuleAccountAddrs(maccPerms map[string][]string) map[string]bool

ModuleAccountAddrs returns all the app's module account addresses.

func NewTestSetup

func NewTestSetup(t testing.TB, options ...SetupOption) (sdk.Context, TestKeepers, TestMsgServers)

NewTestSetup returns initialized instances of all the keepers and message servers of the modules

Types

type Initializer

type Initializer struct {
	Codec      codec.Codec
	Amino      *codec.LegacyAmino
	DB         *dbm.MemDB
	StateStore store.CommitMultiStore
	Logger     log.Logger
}

Initializer allows initializing of each module keeper.

func (*Initializer) Auth

func (i *Initializer) Auth(maccPerms map[string][]string) authkeeper.AccountKeeper

func (*Initializer) Bank

func (i *Initializer) Bank(authKeeper authkeeper.AccountKeeper, maccPerms map[string][]string) bankkeeper.Keeper

func (*Initializer) Distribution

func (i *Initializer) Distribution(
	authKeeper authkeeper.AccountKeeper,
	bankKeeper bankkeeper.Keeper,
	stakingKeeper *stakingkeeper.Keeper,
) distrkeeper.Keeper

func (*Initializer) FeeGrant

func (i *Initializer) FeeGrant(
	authKeeper authkeeper.AccountKeeper,
) feegrantkeeper.Keeper

func (*Initializer) LoadLatest

func (i *Initializer) LoadLatest() error

func (*Initializer) Staking

func (i *Initializer) Staking(
	authKeeper authkeeper.AccountKeeper,
	bankKeeper bankkeeper.Keeper,
) *stakingkeeper.Keeper

func (*Initializer) Upgrade

func (i *Initializer) Upgrade() *upgradekeeper.Keeper

type ProtocolVersionSetter

type ProtocolVersionSetter struct{}

func (ProtocolVersionSetter) SetProtocolVersion

func (vs ProtocolVersionSetter) SetProtocolVersion(uint64)

type SetupOption

type SetupOption func(*SetupOptions)

SetupOption represents an option that can be provided to NewTestSetup

func WithAdditionalModuleAccounts

func WithAdditionalModuleAccounts(maccPerms map[string][]string) SetupOption

WithAdditionalModuleAccounts adds additional module accounts to the testing config.

type SetupOptions

type SetupOptions struct {
	// AdditionalModuleAccountPerms represents any added module account permissions that need to
	// be passed to the keeper initializer
	AdditionalModuleAccountPerms map[string][]string
}

SetupOptions represents the options to configure the setup of a keeper-level integration test.

type TestKeepers

type TestKeepers struct {
	T              testing.TB
	Initializer    *Initializer
	AccountKeeper  authkeeper.AccountKeeper
	BankKeeper     bankkeeper.Keeper
	DistrKeeper    distrkeeper.Keeper
	StakingKeeper  *stakingkeeper.Keeper
	FeeGrantKeeper feegrantkeeper.Keeper
}

TestKeepers holds all keepers used during keeper tests for all modules

func (*TestKeepers) MintToAccount

func (tk *TestKeepers) MintToAccount(ctx sdk.Context, address string, coins sdk.Coins)

MintToAccount mints the specified coins into the account balance.

func (*TestKeepers) MintToModule

func (tk *TestKeepers) MintToModule(ctx sdk.Context, moduleAcc string, coins sdk.Coins)

MintToModule mints the specified coins into the module account balance.

type TestMsgServers

type TestMsgServers struct {
	T testing.TB
}

TestMsgServers holds all message servers used during keeper tests for all modules