rpctest

package
v0.24.0 Latest Latest
Warning

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

 Go to latest Published: Dec 31, 2023 License: ISC Imports: 28 Imported by: 11

README

rpctest

Build Status ISC License GoDoc

Package rpctest provides a btcd-specific RPC testing harness crafting and executing integration tests by driving a btcd 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 btcd. However, the constructs presented are general enough to be adapted to any project wishing to programmatically drive a btcd instance of its systems/integration tests.

Installation and Updating

$ go get -u github.com/btcsuite/btcd/integration/rpctest

License

Package rpctest is licensed under the copyfree ISC License.

Documentation

Overview

Package rpctest provides a btcd-specific RPC testing harness crafting and executing integration tests by driving a `btcd` 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 `btcd`. However, the constructs presented are general enough to be adapted to any project wishing to programmatically drive a `btcd` instance of its systems/integration tests.

Index

Constants

View Source 
const (

	// BlockVersion is the default block version used when generating
	// blocks.
	BlockVersion = 4

	// DefaultMaxConnectionRetries is the default number of times we re-try
	// to connect to the node after starting it.
	DefaultMaxConnectionRetries = 20

	// DefaultConnectionRetryTimeout is the default duration we wait between
	// two connection attempts.
	DefaultConnectionRetryTimeout = 50 * time.Millisecond
)

Variables

View Source 
var (

	// ListenAddressGenerator is a function that is used to generate two
	// listen addresses (host:port), one for the P2P listener and one for
	// the RPC listener. This is exported to allow overwriting of the
	// default behavior which isn't very concurrency safe (just selecting
	// a random port can produce collisions and therefore flakes).
	ListenAddressGenerator = generateListeningAddresses

	// ListenerFormat is the format string that is used to generate local
	// listener addresses.
	ListenerFormat = "127.0.0.1:%d"
)

Functions

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 CreateBlock 

func CreateBlock(prevBlock *btcutil.Block, inclusionTxs []*btcutil.Tx,
	blockVersion int32, blockTime time.Time, miningAddr btcutil.Address,
	mineTo []wire.TxOut, net *chaincfg.Params) (*btcutil.Block, error)

CreateBlock creates a new block building from the previous block with a specified blockversion and timestamp. If the timestamp passed is zero (not initialized), then the timestamp of the previous block will be used plus 1 second is used. Passing nil for the previous block results in a block that builds off of the genesis block for the specified chain.

func GenerateProcessUniqueListenerAddresses added in v0.24.0 

func GenerateProcessUniqueListenerAddresses(pid int) (string, string)

GenerateProcessUniqueListenerAddresses is a function that returns two listener addresses with unique ports per the given process id and should be used to overwrite rpctest's default generator which is prone to use colliding ports.

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 to ensure all active test harnesses are at a consistent state before proceeding to an assertion or check within rpc tests.

func NextAvailablePort added in v0.23.0 

func NextAvailablePort() int

NextAvailablePort returns the first port that is available for listening by a new node. It panics if no port is found and the maximum available TCP port is reached.

func NextAvailablePortForProcess added in v0.24.0 

func NextAvailablePortForProcess(pid int) int

NextAvailablePortForProcess returns the first port that is available for listening by a new node, using a lock file to make sure concurrent access for parallel tasks within the same process don't re-use the same port. It panics if no port is found and the maximum available TCP port is reached.

func TearDownAll 

func TearDownAll() error

TearDownAll tears down all active test harnesses.

Types

type Harness 

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

	// MaxConnRetries is the maximum number of times we re-try to connect to
	// the node after starting it.
	MaxConnRetries int

	// ConnectionRetryTimeout is the duration we wait between two connection
	// attempts.
	ConnectionRetryTimeout time.Duration

	Client      *rpcclient.Client
	BatchClient *rpcclient.Client

	sync.Mutex
	// contains filtered or unexported fields
}

Harness fully encapsulates an active btcd process to provide a unified platform for creating rpc driven integration tests involving btcd. The active btcd node will typically be run in simnet mode in order to allow for easy generation of test blockchains. The active btcd 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.

func New 

func New(activeNet *chaincfg.Params, handlers *rpcclient.NotificationHandlers,
	extraArgs []string, customExePath 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 a custom btcd executable is specified, it will be used to start the harness node. Otherwise a new binary is built on demand.

NOTE: This function is safe for concurrent access.

func (*Harness) ConfirmedBalance 

func (h *Harness) ConfirmedBalance() btcutil.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 btcutil.Amount, change bool) (*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 satoshis-per-byte. The transaction being created can optionally include a change output indicated by the change boolean. 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) GenerateAndSubmitBlock 

func (h *Harness) GenerateAndSubmitBlock(txns []*btcutil.Tx, blockVersion int32,
	blockTime time.Time) (*btcutil.Block, error)

GenerateAndSubmitBlock creates a block whose contents include the passed transactions and submits it to the running simnet node. For generating blocks with only a coinbase tx, callers can simply pass nil instead of transactions to be mined. Additionally, a custom block version can be set by the caller. A blockVersion of -1 indicates that the current default block version should be used. An uninitialized time.Time should be used for the blockTime parameter if one doesn't wish to set a custom time.

This function is safe for concurrent access.

func (*Harness) GenerateAndSubmitBlockWithCustomCoinbaseOutputs 

func (h *Harness) GenerateAndSubmitBlockWithCustomCoinbaseOutputs(
	txns []*btcutil.Tx, blockVersion int32, blockTime time.Time,
	mineTo []wire.TxOut) (*btcutil.Block, error)

GenerateAndSubmitBlockWithCustomCoinbaseOutputs creates a block whose contents include the passed coinbase outputs and transactions and submits it to the running simnet node. For generating blocks with only a coinbase tx, callers can simply pass nil instead of transactions to be mined. Additionally, a custom block version can be set by the caller. A blockVersion of -1 indicates that the current default block version should be used. An uninitialized time.Time should be used for the blockTime parameter if one doesn't wish to set a custom time. The mineTo list of outputs will be added to the coinbase; this is not checked for correctness until the block is submitted; thus, it is the caller's responsibility to ensure that the outputs are correct. If the list is empty, the coinbase reward goes to the wallet managed by the Harness.

This function is safe for concurrent access.

func (*Harness) NewAddress 

func (h *Harness) NewAddress() (btcutil.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' P2P listening address. This allows potential peers (such as SPV peers) created within tests to connect to a given test harness instance.

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 btcutil.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) SendOutputsWithoutChange 

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

SendOutputsWithoutChange creates and sends a transaction that pays to the specified outputs while observing the passed fee rate and ignoring a change output. The passed fee rate should be expressed in sat/b.

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 unspendabe due to being selected to fund a transaction via the CreateTransaction method.

This function is safe for concurrent access.

type HarnessTestCase 

type HarnessTestCase func(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
)

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.