interfacetests

README

This folder contains tests for interfaces that should be run by all implementations.

Note that this kind of testing is normally called contract testing, but that term is overloaded in the smartcontractkit repositories to refer to tests for smart contracts. As such, we will be calling it interface testing, although that term sometimes refers to a slightly different kind of test, we feel that it accurately represents what we are testing and will cause less confusion overall.

Documentation

Index

• Constants
• Variables
• func BindingsByName(bindings []types.BoundContract, name string) []types.BoundContract
• func Compare[T cmp.Ordered](a, b T, op primitives.ComparisonOperator) bool
• func RunCodecInterfaceFuzzTests(f *testing.F, tester CodecInterfaceTester)
• func RunCodecInterfaceTests(t *testing.T, tester CodecInterfaceTester)
• func RunCodecWithStrictArgsInterfaceTest(t *testing.T, tester CodecInterfaceTester)
• func RunContractReaderInterfaceTests[T TestingT[T]](t T, tester ChainComponentsInterfaceTester[T], mockRun bool)
• func RunTests[T TestingT[T]](t T, tester BasicTester[T], tests []Testcase[T])
• func SubmitTransactionToCW[T TestingT[T]](t T, tester ChainComponentsInterfaceTester[T], method string, args any, ...) string
• func WaitForTransactionStatus[T TestingT[T]](t T, tester ChainComponentsInterfaceTester[T], txID string, ...) error
• type AccountStruct
• type BasicTester
• type BatchCallEntry
• type ChainComponentsInterfaceTester
• type CodecInterfaceTester
• type ContractBatchEntry
• type EncodeRequest
• type ExpectedGetLatestValueArgs
  • func (e ExpectedGetLatestValueArgs) String() string
• type FilterEventParams
• type InnerDynamicTestStruct
• type InnerStaticTestStruct
• type LatestParams
• type MidLevelDynamicTestStruct
• type MidLevelStaticTestStruct
• type PrimitiveArgs
• type ReadEntry
• type SomeDynamicTopicEvent
• type TestSelectionSupport
  • func (t *TestSelectionSupport) DisableTests(testIDs []string)
  • func (t TestSelectionSupport) IsDisabled(testID string) bool
• type TestStruct
  • func CreateTestStruct[T any](i int, tester BasicTester[T]) TestStruct
• type TestStructMissingField
• type TestStructWithExtraField
• type Testcase
• type TestingT

Constants

const (
	ContractReaderGetLatestValueAsValuesDotValue                              = "Gets the latest value as a values.Value"
	ContractReaderGetLatestValueNoArgumentsAndPrimitiveReturnAsValuesDotValue = "Get latest value without arguments and with primitive return as a values.Value"
	ContractReaderGetLatestValueNoArgumentsAndSliceReturnAsValueDotValue      = "Get latest value without arguments and with slice return as a values.Value"
	ContractReaderGetLatestValue                                              = "Gets the latest value"
	ContractReaderGetLatestValueWithHeadData                                  = "Gets the latest value with head data"
	ContractReaderGetLatestValueWithPrimitiveReturn                           = "Get latest value without arguments and with primitive return"
	ContractReaderGetLatestValueBasedOnConfidenceLevel                        = "Get latest value based on confidence level"
	ContractReaderGetLatestValueFromMultipleContractsNamesSameFunction        = "Get latest value allows multiple contract names to have the same function "
	ContractReaderGetLatestValueWithModifiersUsingOwnMapstrctureOverrides     = "Get latest value wraps config with modifiers using its own mapstructure overrides"
	ContractReaderGetLatestValueNoArgumentsAndSliceReturn                     = "Get latest value without arguments and with slice return"
)

GetLatestValue method

const (
	ContractReaderGetLatestValueGetsLatestForEvent                      = "Get latest value gets latest event"
	ContractReaderGetLatestValueBasedOnConfidenceLevelForEvent          = "Get latest event based on provided confidence level"
	ContractReaderGetLatestValueReturnsNotFoundWhenNotTriggeredForEvent = "Get latest value returns not found if event was never triggered"
	ContractReaderGetLatestValueWithFilteringForEvent                   = "Get latest value gets latest event with filtering"
)

GetLatestValue event

const (
	ContractReaderBatchGetLatestValue                                                   = "BatchGetLatestValues works"
	ContractReaderBatchGetLatestValueNoArgumentsPrimitiveReturn                         = "BatchGetLatestValues works without arguments and with primitive return"
	ContractReaderBatchGetLatestValueMultipleContractNamesSameFunction                  = "BatchGetLatestValues allows multiple contract names to have the same function Name"
	ContractReaderBatchGetLatestValueNoArgumentsWithSliceReturn                         = "BatchGetLatestValue without arguments and with slice return"
	ContractReaderBatchGetLatestValueWithModifiersOwnMapstructureOverride               = "BatchGetLatestValues wraps config with modifiers using its own mapstructure overrides"
	ContractReaderBatchGetLatestValueDifferentParamsResultsRetainOrder                  = "BatchGetLatestValues supports same read with different params and results retain order from request"
	ContractReaderBatchGetLatestValueDifferentParamsResultsRetainOrderMultipleContracts = "" /* 128-byte string literal not displayed */
	ContractReaderBatchGetLatestValueSetsErrorsProperly                                 = "BatchGetLatestValues sets errors properly"
)

BatchGet

const (
	ContractReaderQueryKeyNotFound                     = "QueryKey returns not found if sequence never happened"
	ContractReaderQueryKeyReturnsData                  = "QueryKey returns sequence data properly"
	ContractReaderQueryKeyReturnsDataAsValuesDotValue  = "QueryKey returns sequence data properly as values.Value"
	ContractReaderQueryKeyCanFilterWithValueComparator = "QueryKey can filter data with value comparator"
	ContractReaderQueryKeyCanLimitResultsWithCursor    = "QueryKey can limit results with cursor"
)

Query key

const (
	ContractReaderQueryKeysReturnsDataTwoEventTypes     = "QueryKeys returns sequence data properly for two event types"
	ContractReaderQueryKeysNotFound                     = "QueryKeys returns not found if sequence never happened"
	ContractReaderQueryKeysReturnsData                  = "QueryKeys returns sequence data properly"
	ContractReaderQueryKeysReturnsDataAsValuesDotValue  = "QueryKeys returns sequence data properly as values.Value"
	ContractReaderQueryKeysCanFilterWithValueComparator = "QueryKeys can filter data with value comparator"
	ContractReaderQueryKeysCanLimitResultsWithCursor    = "QueryKeys can limit results with cursor"
)

Query keys

const (
	AnyValueToReadWithoutAnArgument             = uint64(3)
	AnyDifferentValueToReadWithoutAnArgument    = uint64(1990)
	MethodTakingLatestParamsReturningTestStruct = "GetLatestValues"
	MethodReturningUint64                       = "GetPrimitiveValue"
	MethodReturningAlterableUint64              = "GetAlterablePrimitiveValue"
	MethodReturningUint64Slice                  = "GetSliceValue"
	MethodReturningSeenStruct                   = "GetSeenStruct"
	MethodSettingStruct                         = "addTestStruct"
	MethodSettingUint64                         = "setAlterablePrimitiveValue"
	MethodTriggeringEvent                       = "triggerEvent"
	MethodTriggeringEventWithDynamicTopic       = "triggerEventWithDynamicTopic"
	DynamicTopicEventName                       = "TriggeredEventWithDynamicTopic"
	EventName                                   = "SomeEvent"
	EventNameField                              = EventName + ".Field"
	ProtoTest                                   = "ProtoTest"
	ProtoTestIntComparator                      = ProtoTest + ".IntComparator"
	ProtoTestStringComparator                   = ProtoTest + ".StringComparator"
	EventWithFilterName                         = "SomeEventToFilter"
	AnyContractName                             = "TestContract"
	AnySecondContractName                       = "Not" + AnyContractName
)

const (
	TestItemType            = "TestItem"
	TestItemSliceType       = "TestItemSliceType"
	TestItemArray1Type      = "TestItemArray1Type"
	TestItemArray2Type      = "TestItemArray2Type"
	TestItemWithConfigExtra = "TestItemWithConfigExtra"
	NilType                 = "NilType"
)

const AnyExtraValue = 3

Variables

var AnySliceToReadWithoutAnArgument = []uint64{3, 4}

Functions

func BindingsByName

func BindingsByName(bindings []types.BoundContract, name string) []types.BoundContract

func Compare

func Compare[T cmp.Ordered](a, b T, op primitives.ComparisonOperator) bool

func RunCodecInterfaceFuzzTests

func RunCodecInterfaceFuzzTests(f *testing.F, tester CodecInterfaceTester)

func RunCodecInterfaceTests

func RunCodecInterfaceTests(t *testing.T, tester CodecInterfaceTester)

func RunCodecWithStrictArgsInterfaceTest

func RunCodecWithStrictArgsInterfaceTest(t *testing.T, tester CodecInterfaceTester)

RunCodecWithStrictArgsInterfaceTest is meant to be used by codecs that don't pad They can assure that the right argument size is verified. Padding makes that harder/impossible to verify for come codecs. However, the extra verification is nice to have when possible.

func RunContractReaderInterfaceTests

func RunContractReaderInterfaceTests[T TestingT[T]](t T, tester ChainComponentsInterfaceTester[T], mockRun bool)

func RunTests

func RunTests[T TestingT[T]](t T, tester BasicTester[T], tests []Testcase[T])

Tests execution utility function that will consider enabled / disabled test cases according to Basic Tester configuration.

func SubmitTransactionToCW

func SubmitTransactionToCW[T TestingT[T]](t T, tester ChainComponentsInterfaceTester[T], method string, args any, contract types.BoundContract, status types.TransactionStatus) string

SubmitTransactionToCW submits a transaction to the ContractWriter and waits for it to reach the given status.

func WaitForTransactionStatus

func WaitForTransactionStatus[T TestingT[T]](t T, tester ChainComponentsInterfaceTester[T], txID string, status types.TransactionStatus, mockRun bool) error

WaitForTransactionStatus waits for a transaction to reach the given status.

Types

type AccountStruct

type AccountStruct struct {
	Account    []byte
	AccountStr string
}

type BasicTester

type BasicTester[T any] interface {
	Setup(t T)
	Name() string
	GetAccountBytes(i int) []byte
	GetAccountString(i int) string
	IsDisabled(testID string) bool
	DisableTests(testIDs []string)
}

type BatchCallEntry

type BatchCallEntry map[types.BoundContract]ContractBatchEntry

type ChainComponentsInterfaceTester

type ChainComponentsInterfaceTester[T TestingT[T]] interface {
	BasicTester[T]
	GetContractReader(t T) types.ContractReader
	GetContractWriter(t T) types.ContractWriter
	GetBindings(t T) []types.BoundContract
	// DirtyContracts signals to the underlying tester than the test contracts are dirty, i.e. the state has been changed such that
	// new, fresh contracts should be deployed. This usually happens after a value is written to the contract via
	// the ContractWriter.
	DirtyContracts()
	MaxWaitTimeForEvents() time.Duration
	// GenerateBlocksTillConfidenceLevel is only used by the internal common tests, all other tests can/should
	// rely on the ContractWriter waiting for actual blocks to be mined.
	GenerateBlocksTillConfidenceLevel(t T, contractName, readName string, confidenceLevel primitives.ConfidenceLevel)
}

type CodecInterfaceTester

type CodecInterfaceTester interface {
	BasicTester[*testing.T]
	EncodeFields(t *testing.T, request *EncodeRequest) []byte
	GetCodec(t *testing.T) types.Codec

	// IncludeArrayEncodingSizeEnforcement is here in case there's no way to have fixed arrays in the encoded values
	IncludeArrayEncodingSizeEnforcement() bool
}

type ContractBatchEntry

type ContractBatchEntry []ReadEntry

type EncodeRequest

type EncodeRequest struct {
	TestStructs  []TestStruct
	ExtraField   bool
	MissingField bool
	TestOn       string
}

type ExpectedGetLatestValueArgs

type ExpectedGetLatestValueArgs struct {
	ContractName, ReadName string
	ConfidenceLevel        primitives.ConfidenceLevel
	Params, ReturnVal      any
}

func (ExpectedGetLatestValueArgs) String

func (e ExpectedGetLatestValueArgs) String() string

type FilterEventParams

type FilterEventParams struct {
	Field int32
}

type InnerDynamicTestStruct

type InnerDynamicTestStruct struct {
	I int
	S string
}

type InnerStaticTestStruct

type InnerStaticTestStruct struct {
	I int
	A []byte
}

type LatestParams

type LatestParams struct {
	// I should be > 0
	I int
}

type MidLevelDynamicTestStruct

type MidLevelDynamicTestStruct struct {
	FixedBytes [2]byte
	Inner      InnerDynamicTestStruct
}

type MidLevelStaticTestStruct

type MidLevelStaticTestStruct struct {
	FixedBytes [2]byte
	Inner      InnerStaticTestStruct
}

type PrimitiveArgs

type PrimitiveArgs struct {
	Value uint64
}

type ReadEntry

type ReadEntry struct {
	Name        string
	ReturnValue any
}

type SomeDynamicTopicEvent

type SomeDynamicTopicEvent struct {
	Field string
}

type TestSelectionSupport

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

func (*TestSelectionSupport) DisableTests

func (t *TestSelectionSupport) DisableTests(testIDs []string)

func (TestSelectionSupport) IsDisabled

func (t TestSelectionSupport) IsDisabled(testID string) bool

type TestStruct

type TestStruct struct {
	Field               *int32
	OracleID            commontypes.OracleID
	OracleIDs           [32]commontypes.OracleID
	AccountStruct       AccountStruct
	Accounts            [][]byte
	DifferentField      string
	BigField            *big.Int
	NestedDynamicStruct MidLevelDynamicTestStruct
	NestedStaticStruct  MidLevelStaticTestStruct
}

func CreateTestStruct

func CreateTestStruct[T any](i int, tester BasicTester[T]) TestStruct

type TestStructMissingField

type TestStructMissingField struct {
	DifferentField      string
	OracleID            commontypes.OracleID
	OracleIDs           [32]commontypes.OracleID
	AccountStruct       AccountStruct
	Accounts            [][]byte
	BigField            *big.Int
	NestedDynamicStruct MidLevelDynamicTestStruct
	NestedStaticStruct  MidLevelStaticTestStruct
}

type TestStructWithExtraField

type TestStructWithExtraField struct {
	TestStruct
	ExtraField int
}

type Testcase

type Testcase[T any] struct {
	Name string
	Test func(t T)
}

type TestingT

type TestingT[T any] interface {
	tests.TestingT
	Failed() bool
	Run(name string, f func(t T)) bool
}