rpctest

README

rpctest

Package rpctest provides a exccd-specific RPC testing harness crafting and executing integration tests by driving a exccd instance via the RPC interface. Each instance of an active harness comes equipped with a simple in-memory HD wallet capable of properly syncing to the generated chain, creating new addresses, and crafting fully signed transactions paying to an arbitrary set of outputs.

This package was designed specifically to act as an RPC testing harness for exccd. However, the constructs presented are general enough to be adapted to any project wishing to programmatically drive a exccd instance of its systems/integration tests.

Installation and Updating

This package is part of the github.com/EXCCoin/exccd module. Use the standard go tooling for working with modules to incorporate it.

License

Package rpctest is licensed under the copyfree ISC License.

Documentation

Overview

Package rpctest provides a dcrd-specific RPC testing harness crafting and executing integration tests by driving a `dcrd` instance via the `RPC` interface. Each instance of an active harness comes equipped with a simple in-memory HD wallet capable of properly syncing to the generated chain, creating new addresses, and crafting fully signed transactions paying to an arbitrary set of outputs.

This package was designed specifically to act as an RPC testing harness for `dcrd`. However, the constructs presented are general enough to be adapted to any project wishing to programmatically drive a `dcrd` instance of its systems/integration tests.

Index

• func AdjustedSimnetMiner(ctx context.Context, client *rpcclient.Client, nb uint32) ([]*chainhash.Hash, error)
• func ConnectNode(from *Harness, to *Harness) error
• func JoinNodes(nodes []*Harness, joinType JoinType) error
• func NodesConnected(ctx context.Context, from, to *Harness, allowReverse bool) (bool, error)
• func PanicAll(t *testing.T)
• func RemoveNode(ctx context.Context, from *Harness, to *Harness) error
• func SetPathToDCRD(fnScopePathToDCRD string)
• func TearDownAll() error
• type Harness
  • func ActiveHarnesses() []*Harness
  • func New(t *testing.T, activeNet *chaincfg.Params, ...) (*Harness, error)
  • func (h *Harness) ConfirmedBalance() dcrutil.Amount
  • func (h *Harness) CreateTransaction(targetOutputs []*wire.TxOut, feeRate dcrutil.Amount) (*wire.MsgTx, error)
  • func (h *Harness) NewAddress() (stdaddr.Address, error)
  • func (h *Harness) P2PAddress() string
  • func (h *Harness) RPCConfig() rpcclient.ConnConfig
  • func (h *Harness) SendOutputs(targetOutputs []*wire.TxOut, feeRate dcrutil.Amount) (*chainhash.Hash, error)
  • func (h *Harness) SetUp(createTestChain bool, numMatureOutputs uint32) error
  • func (h *Harness) TearDown() error
  • func (h *Harness) UnlockOutputs(inputs []*wire.TxIn)
• type HarnessTestCase
• type JoinType
• type VotingWallet
  • func NewVotingWallet(ctx context.Context, hn *Harness) (*VotingWallet, error)
  • func (w *VotingWallet) GenerateBlocks(ctx context.Context, nb uint32) ([]*chainhash.Hash, error)
  • func (w *VotingWallet) LimitNbVotes(newLimit int) error
  • func (w *VotingWallet) SetErrorReporting(f func(err error))
  • func (w *VotingWallet) SetMiner(f func(context.Context, uint32) ([]*chainhash.Hash, error))
  • func (w *VotingWallet) Start() error
  • func (w *VotingWallet) Stop()
  • func (w *VotingWallet) VoteForTSpends(votes []*stake.TreasuryVoteTuple)

Functions

func AdjustedSimnetMiner

func AdjustedSimnetMiner(ctx context.Context, client *rpcclient.Client, nb uint32) ([]*chainhash.Hash, error)

AdjustedSimnetMiner is an alternative miner function that instead of relying on the backing node to mine a block, fetches the work required for the next block and mines the block itself while adjusting the timestamp so that (on simnet) no difficulty increase is trigered. After finding a block, it automatically publishes it to the underlying node.

This is only applicable for tests that run on simnet or other networks that have a target block per count of 1 second.

func ConnectNode

func ConnectNode(from *Harness, to *Harness) error

ConnectNode establishes a new peer-to-peer connection between the "from" harness and the "to" harness. The connection made is flagged as persistent, therefore in the case of disconnects, "from" will attempt to reestablish a connection to the "to" harness.

func JoinNodes

func JoinNodes(nodes []*Harness, joinType JoinType) error

JoinNodes is a synchronization tool used to block until all passed nodes are fully synced with respect to an attribute. This function will block for a period of time, finally returning once all nodes are synced according to the passed JoinType. This function be used to ensure all active test harnesses are at a consistent state before proceeding to an assertion or check within rpc tests.

func NodesConnected

func NodesConnected(ctx context.Context, from, to *Harness, allowReverse bool) (bool, error)

NodesConnected verifies whether there is a connection via the p2p interface between the specified nodes. If allowReverse is true, connectivity is also checked in the reverse direction (to->from).

func PanicAll

func PanicAll(t *testing.T)

PanicAll tears down all active test harnesses. XXX We ignore the mutex because it is *hopefully* locked when this is called.

func RemoveNode

func RemoveNode(ctx context.Context, from *Harness, to *Harness) error

RemoveNode removes the peer-to-peer connection between the "from" harness and the "to" harness. The connection is only removed in this direction, therefore if the reverse connection exists, the nodes may still be connected.

This function returns an error if the nodes were not previously connected.

func SetPathToDCRD

func SetPathToDCRD(fnScopePathToDCRD string)

SetPathToDCRD sets the package level dcrd executable. All calls to New will use the dcrd located there throughout their life. If not set upon the first call to New, a dcrd will be created in a temporary directory and pathToDCRD set automatically.

NOTE: This function is safe for concurrent access, but care must be taken when setting different paths and using New, as whatever is at pathToDCRD at the time will be identified with that node.

func TearDownAll

func TearDownAll() error

TearDownAll tears down all active test harnesses. XXX harness.TearDown() can hang with mutex held.

Types

type Harness

type Harness struct {
	// ActiveNet is the parameters of the blockchain the Harness belongs
	// to.
	ActiveNet *chaincfg.Params

	Node *rpcclient.Client

	sync.Mutex
	// contains filtered or unexported fields
}

Harness fully encapsulates an active dcrd process to provide a unified platform for creating rpc driven integration tests involving dcrd. The active dcrd node will typically be run in simnet mode in order to allow for easy generation of test blockchains. The active dcrd process is fully managed by Harness, which handles the necessary initialization, and teardown of the process along with any temporary directories created as a result. Multiple Harness instances may be run concurrently, in order to allow for testing complex scenarios involving multiple nodes. The harness also includes an in-memory wallet to streamline various classes of tests.

func ActiveHarnesses

func ActiveHarnesses() []*Harness

ActiveHarnesses returns a slice of all currently active test harnesses. A test harness if considered "active" if it has been created, but not yet torn down. XXX this is dumb because whatever happens after this call is racing over the Harness pointers.

func New

func New(t *testing.T, activeNet *chaincfg.Params, handlers *rpcclient.NotificationHandlers, extraArgs []string) (*Harness, error)

New creates and initializes new instance of the rpc test harness. Optionally, websocket handlers and a specified configuration may be passed. In the case that a nil config is passed, a default configuration will be used. If pathToDCRD has not been set and working within the dcrd repository, a dcrd executable created from the directory at rpctest/../ (dcrd repo's root directory) will be created in a temporary directory. pathToDCRD will be set as that file's location. If pathToDCRD has already been set, the executable at that location will be used.

NOTE: This function is safe for concurrent access, but care must be taken when calling New with different dcrd executables, as whatever is at pathToDCRD at the time will be identified with that node.

func (*Harness) ConfirmedBalance

func (h *Harness) ConfirmedBalance() dcrutil.Amount

ConfirmedBalance returns the confirmed balance of the Harness' internal wallet.

This function is safe for concurrent access.

func (*Harness) CreateTransaction

func (h *Harness) CreateTransaction(targetOutputs []*wire.TxOut, feeRate dcrutil.Amount) (*wire.MsgTx, error)

CreateTransaction returns a fully signed transaction paying to the specified outputs while observing the desired fee rate. The passed fee rate should be expressed in atoms-per-byte. Any unspent outputs selected as inputs for the crafted transaction are marked as unspendable in order to avoid potential double-spends by future calls to this method. If the created transaction is cancelled for any reason then the selected inputs MUST be freed via a call to UnlockOutputs. Otherwise, the locked inputs won't be returned to the pool of spendable outputs.

This function is safe for concurrent access.

func (*Harness) NewAddress

func (h *Harness) NewAddress() (stdaddr.Address, error)

NewAddress returns a fresh address spendable by the Harness' internal wallet.

This function is safe for concurrent access.

func (*Harness) P2PAddress

func (h *Harness) P2PAddress() string

P2PAddress returns the harness node's configured listening address for P2P connections.

Note that to connect two different harnesses, it's preferable to use the ConnectNode() function, which handles cases like already connected peers and ensures the connection actually takes place.

func (*Harness) RPCConfig

func (h *Harness) RPCConfig() rpcclient.ConnConfig

RPCConfig returns the harnesses current rpc configuration. This allows other potential RPC clients created within tests to connect to a given test harness instance.

func (*Harness) SendOutputs

func (h *Harness) SendOutputs(targetOutputs []*wire.TxOut, feeRate dcrutil.Amount) (*chainhash.Hash, error)

SendOutputs creates, signs, and finally broadcasts a transaction spending the harness' available mature coinbase outputs creating new outputs according to targetOutputs.

This function is safe for concurrent access.

func (*Harness) SetUp

func (h *Harness) SetUp(createTestChain bool, numMatureOutputs uint32) error

SetUp initializes the rpc test state. Initialization includes: starting up a simnet node, creating a websockets client and connecting to the started node, and finally: optionally generating and submitting a testchain with a configurable number of mature coinbase outputs coinbase outputs.

NOTE: This method and TearDown should always be called from the same goroutine as they are not concurrent safe.

func (*Harness) TearDown

func (h *Harness) TearDown() error

TearDown stops the running rpc test instance. All created processes are killed, and temporary directories removed.

NOTE: This method and SetUp should always be called from the same goroutine as they are not concurrent safe.

func (*Harness) UnlockOutputs

func (h *Harness) UnlockOutputs(inputs []*wire.TxIn)

UnlockOutputs unlocks any outputs which were previously marked as unspendable due to being selected to fund a transaction via the CreateTransaction method.

This function is safe for concurrent access.

type HarnessTestCase

type HarnessTestCase func(ctx context.Context, r *Harness, t *testing.T)

HarnessTestCase represents a test-case which utilizes an instance of the Harness to exercise functionality.

type JoinType

type JoinType uint8

JoinType is an enum representing a particular type of "node join". A node join is a synchronization tool used to wait until a subset of nodes have a consistent state with respect to an attribute.

const (
	// Blocks is a JoinType which waits until all nodes share the same
	// block height.
	Blocks JoinType = iota

	// Mempools is a JoinType which blocks until all nodes have identical
	// mempool.
	Mempools
)

type VotingWallet

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

VotingWallet stores the state for a simulated voting wallet. Once it is started, it will receive notifications from the associated harness, purchase tickets and vote on blocks as necessary to keep the chain going.

This currently only implements the bare minimum requirements for maintaining a functioning voting wallet and does not handle reorgs, multiple voting and ticket buying wallets, setting vote bits, expired/missed votes, etc.

All operations (after initial funding) are done solely via stake transactions, so no additional regular transactions are published. This is ideal for use in test suites that require a large (greater than SVH) number of blocks.

func NewVotingWallet

func NewVotingWallet(ctx context.Context, hn *Harness) (*VotingWallet, error)

NewVotingWallet creates a new minimal voting wallet for the given harness. This wallet should be able to maintain the chain generated by the miner node of the harness working after it has passed SVH (Stake Validation Height) by continuously buying tickets and voting on them.

func (*VotingWallet) GenerateBlocks

func (w *VotingWallet) GenerateBlocks(ctx context.Context, nb uint32) ([]*chainhash.Hash, error)

GenerateBlocks generates blocks while ensuring the chain will continue past SVH indefinitely. This will generate a block then wait for the votes from this wallet to be sent and tickets to be purchased before either generating the next block or returning.

This function will either return the hashes of the generated blocks or an error if, after generating a candidate block, votes and tickets aren't submitted in a timely fashion.

func (*VotingWallet) LimitNbVotes

func (w *VotingWallet) LimitNbVotes(newLimit int) error

LimitNbVotes limits the number of votes issued by the voting wallet to the given amount, which is useful for testing scenarios where less than the total number of votes per block are cast in the network.

Note that due to limitations in the current implementation of the voting wallet, you can only reduce this amount (never increase it) and simnet voting will stop once CoinbaseMaturity blocks have passed (so this needs to be used only at the end of a test run).

func (*VotingWallet) SetErrorReporting

func (w *VotingWallet) SetErrorReporting(f func(err error))

SetErrorReporting allows users of the voting wallet to specify a function that will be called whenever an error happens while purchasing tickets or generating votes.

func (*VotingWallet) SetMiner

func (w *VotingWallet) SetMiner(f func(context.Context, uint32) ([]*chainhash.Hash, error))

SetMiner allows users of the voting wallet to specify a function that will be used to mine new blocks instead of using the regular Generate function of the configured rpcclient.

This allows callers to use a custom function to generate blocks, such as one that allows faster mining in simnet.

func (*VotingWallet) Start

func (w *VotingWallet) Start() error

Start stars the goroutines necessary for this voting wallet to function.

func (*VotingWallet) Stop

func (w *VotingWallet) Stop()

Stop signals all goroutines from this wallet to stop their functions.

func (*VotingWallet) VoteForTSpends

func (w *VotingWallet) VoteForTSpends(votes []*stake.TreasuryVoteTuple)

VoteForTSpends sets the wallet to vote for the provided tspends when creating vote transactions.