A transaction testing environment. More...

Collaboration diagram for ripple::test::jtx::Env:

[legend]

Classes
struct	AppBundle

Public Member Functions
	Env ()=delete

Env &	operator= (Env const &)=delete

	Env (Env const &)=delete

	Env (beast::unit_test::suite &suite_, std::unique_ptr< Config > config, FeatureBitset features, std::unique_ptr< Logs > logs=nullptr, beast::severities::Severity thresh=beast::severities::kError)
	Create Env using suite, Config pointer, and explicit features. More...

	Env (beast::unit_test::suite &suite_, FeatureBitset features)
	Create Env with default config and specified features. More...

	Env (beast::unit_test::suite &suite_, std::unique_ptr< Config > config, std::unique_ptr< Logs > logs=nullptr, beast::severities::Severity thresh=beast::severities::kError)
	Create Env using suite and Config pointer. More...

	Env (beast::unit_test::suite &suite_)
	Create Env with only the current test suite. More...

virtual	~Env ()=default

Application &	app ()

Application const &	app () const

ManualTimeKeeper &	timeKeeper ()

NetClock::time_point	now ()
	Returns the current network time. More...

AbstractClient &	client ()
	Returns the connected client. More...

template<class... Args>
Json::Value	rpc (std::unordered_map< std::string, std::string > const &headers, std::string const &cmd, Args &&... args)
	Execute an RPC command. More...

template<class... Args>
Json::Value	rpc (std::string const &cmd, Args &&... args)

std::shared_ptr< OpenView const >	current () const
	Returns the current ledger. More...

std::shared_ptr< ReadView const >	closed ()
	Returns the last closed ledger. More...

bool	close (NetClock::time_point closeTime, std::optional< std::chrono::milliseconds > consensusDelay=std::nullopt)
	Close and advance the ledger. More...

template<class Rep , class Period >
bool	close (std::chrono::duration< Rep, Period > const &elapsed)
	Close and advance the ledger. More...

bool	close ()
	Close and advance the ledger. More...

void	trace (int howMany=-1)
	Turn on JSON tracing. More...

void	notrace ()
	Turn off JSON tracing. More...

void	disable_sigs ()
	Turn off signature checks. More...

void	memoize (Account const &account)
	Associate AccountID with account. More...

PrettyAmount	balance (Account const &account) const
	Returns the XRP balance on an account. More...

std::uint32_t	seq (Account const &account) const
	Returns the next sequence number on account. More...

PrettyAmount	balance (Account const &account, Issue const &issue) const
	Return the balance on an account. More...

std::shared_ptr< SLE const >	le (Account const &account) const
	Return an account root. More...

std::shared_ptr< SLE const >	le (Keylet const &k) const
	Return a ledger entry. More...

template<class JsonValue , class... FN>
JTx	jt (JsonValue &&jv, FN const &... fN)
	Create a JTx from parameters. More...

template<class JsonValue , class... FN>
Json::Value	json (JsonValue &&jv, FN const &... fN)
	Create JSON from parameters. More...

template<class... Args>
void	require (Args const &... args)
	Check a set of requirements. More...

virtual void	submit (JTx const &jt)
	Submit an existing JTx. More...

void	sign_and_submit (JTx const &jt, Json::Value params=Json::nullValue)
	Use the submit RPC command with a provided JTx object. More...

void	postconditions (JTx const &jt, TER ter, bool didApply)
	Check expected postconditions of JTx submission. More...

TER	ter () const
	Return the TER for the last JTx. More...

std::shared_ptr< STObject const >	meta ()
	Return metadata for the last JTx. More...

std::shared_ptr< STTx const >	tx () const
	Return the tx data for the last JTx. More...

void	enableFeature (uint256 const feature)

void	disableFeature (uint256 const feature)

template<class Arg , class... Args>
void	fund (STAmount const &amount, Arg const &arg, Args const &... args)
	Create a new account with some XRP. More...


Account const &	lookup (AccountID const &id) const
	Returns the Account given the AccountID. More...

Account const &	lookup (std::string const &base58ID) const


template<class JsonValue , class... FN>
void	apply (JsonValue &&jv, FN const &... fN)
	Apply funclets and submit. More...

template<class JsonValue , class... FN>
void	operator() (JsonValue &&jv, FN const &... fN)


void	trust (STAmount const &amount, Account const &account)
	Establish trust lines. More...

template<class... Accounts>
void	trust (STAmount const &amount, Account const &to0, Account const &to1, Accounts const &... toN)

Static Public Member Functions
static std::pair< TER, bool >	parseResult (Json::Value const &jr)
	Gets the TER result and `didApply` flag from a RPC Json result object. More...

Public Attributes
beast::unit_test::suite &	test

Account const &	master = Account::master

const beast::Journal	journal

Protected Member Functions
Json::Value	do_rpc (std::vector< std::string > const &args, std::unordered_map< std::string, std::string > const &headers={})

void	autofill_sig (JTx &jt)

virtual void	autofill (JTx &jt)

std::shared_ptr< STTx const >	st (JTx const &jt)
	Create a STTx from a JTx The framework requires that JSON is valid. More...

template<class... FN>
void	invoke (STTx &stx, FN const &... fN)

template<class... FN>
void	invoke (JTx &jt, FN const &... fN)

Protected Attributes
int	trace_ = 0

TestStopwatch	stopwatch_

uint256	txid_

TER	ter_ = tesSUCCESS

std::unordered_map< AccountID, Account >	map_

Private Member Functions
void	fund (bool setDefaultRipple, STAmount const &amount, Account const &account)

void	fund_arg (STAmount const &amount, Account const &account)

template<std::size_t N>
void	fund_arg (STAmount const &amount, std::array< Account, N > const &list)

Private Attributes
AppBundle	bundle_

Detailed Description

A transaction testing environment.

Definition at line 116 of file Env.h.

Constructor & Destructor Documentation

◆ Env() [1/6]

ripple::test::jtx::Env::Env ( )

delete

◆ Env() [2/6]

ripple::test::jtx::Env::Env ( Env const & )

delete

◆ Env() [3/6]

ripple::test::jtx::Env::Env	(	beast::unit_test::suite &	suite_,
		std::unique_ptr< Config >	config,
		FeatureBitset	features,
		std::unique_ptr< Logs >	logs = `nullptr`,
		beast::severities::Severity	thresh = `beast::severities::kError`
	)

Create Env using suite, Config pointer, and explicit features.

This constructor will create an Env with the specified configuration and takes ownership the passed Config pointer. Features will be enabled according to rules described below (see next constructor).

Parameters

suite_	the current unit_test::suite
config	The desired Config - ownership will be taken by moving the pointer. See envconfig and related functions for common config tweaks.
args	with_only_features() to explicitly enable or supported_features_except() to enable all and disable specific features.

Definition at line 166 of file Env.h.

◆ Env() [4/6]

ripple::test::jtx::Env::Env	(	beast::unit_test::suite &	suite_,
		FeatureBitset	features
	)

Create Env with default config and specified features.

This constructor will create an Env with the standard Env configuration (from envconfig()) and features explicitly specified. Use with_only_features(...) or supported_features_except(...) to create a collection of features appropriate for passing here.

Parameters

suite_	the current unit_test::suite
args	collection of features

Definition at line 196 of file Env.h.

◆ Env() [5/6]

ripple::test::jtx::Env::Env	(	beast::unit_test::suite &	suite_,
		std::unique_ptr< Config >	config,
		std::unique_ptr< Logs >	logs = `nullptr`,
		beast::severities::Severity	thresh = `beast::severities::kError`
	)

Create Env using suite and Config pointer.

This constructor will create an Env with the specified configuration and takes ownership the passed Config pointer. All supported amendments are enabled by this version of the constructor.

Parameters

suite_	the current unit_test::suite
config	The desired Config - ownership will be taken by moving the pointer. See envconfig and related functions for common config tweaks.

Definition at line 213 of file Env.h.

◆ Env() [6/6]

ripple::test::jtx::Env::Env ( beast::unit_test::suite & suite_ )

Create Env with only the current test suite.

This constructor will create an Env with the standard test Env configuration (from envconfig()) and all supported amendments enabled.

Parameters

suite_ the current unit_test::suite

Definition at line 234 of file Env.h.

◆ ~Env()

virtual ripple::test::jtx::Env::~Env ( )

virtualdefault

Member Function Documentation

◆ operator=()

Env& ripple::test::jtx::Env::operator= ( Env const & )

delete

◆ app() [1/2]

Application& ripple::test::jtx::Env::app ( )

Definition at line 241 of file Env.h.

◆ app() [2/2]

Application const& ripple::test::jtx::Env::app ( ) const

Definition at line 247 of file Env.h.

◆ timeKeeper()

ManualTimeKeeper& ripple::test::jtx::Env::timeKeeper ( )

Definition at line 253 of file Env.h.

◆ now()

NetClock::time_point ripple::test::jtx::Env::now ( )

Returns the current network time.

Note: This is manually advanced when ledgers close or by callers.

Definition at line 264 of file Env.h.

◆ client()

AbstractClient& ripple::test::jtx::Env::client ( )

Returns the connected client.

Definition at line 271 of file Env.h.

◆ rpc() [1/2]

template<class... Args>

Json::Value ripple::test::jtx::Env::rpc	(	std::unordered_map< std::string, std::string > const &	headers,
		std::string const &	cmd,
		Args &&...	args
	)

Execute an RPC command.

The command is examined and used to build the correct JSON as per the arguments.

Definition at line 687 of file Env.h.

◆ rpc() [2/2]

template<class... Args>

Json::Value ripple::test::jtx::Env::rpc	(	std::string const &	cmd,
		Args &&...	args
	)

Definition at line 698 of file Env.h.

◆ current()

std::shared_ptr<OpenView const> ripple::test::jtx::Env::current ( ) const

Returns the current ledger.

This is a non-modifiable snapshot of the open ledger at the moment of the call. Transactions applied after the call to open() will not be visible.

Definition at line 300 of file Env.h.

◆ closed()

std::shared_ptr< ReadView const > ripple::test::jtx::Env::closed ( )

Returns the last closed ledger.

The open ledger is built on top of the last closed ledger. When the open ledger is closed, it becomes the new closed ledger and a new open ledger takes its place.

Definition at line 115 of file Env.cpp.

◆ close() [1/3]

bool ripple::test::jtx::Env::close	(	NetClock::time_point	closeTime,
		std::optional< std::chrono::milliseconds >	consensusDelay = `std::nullopt`
	)

Close and advance the ledger.

The resulting close time will be different and greater than the previous close time, and at or after the passed-in close time.

Effects:

Creates a new closed ledger from the last
closed ledger.

All transactions that made it into the open
ledger are applied to the closed ledger.

The Application network time is set to
the close time of the resulting ledger.

Returns: true if no error, false if error

Definition at line 121 of file Env.cpp.

◆ close() [2/3]

template<class Rep , class Period >

bool ripple::test::jtx::Env::close ( std::chrono::duration< Rep, Period > const & elapsed )

Close and advance the ledger.

The time is calculated as the duration from the previous ledger closing time.

Returns: true if no error, false if error

Definition at line 348 of file Env.h.

◆ close() [3/3]

bool ripple::test::jtx::Env::close ( )

Close and advance the ledger.

The time is calculated as five seconds from the previous ledger closing time.

Returns: true if no error, false if error

Definition at line 362 of file Env.h.

◆ trace()

void ripple::test::jtx::Env::trace ( int howMany = -1 )

Turn on JSON tracing.

With no arguments, trace all

Definition at line 372 of file Env.h.

◆ notrace()

void ripple::test::jtx::Env::notrace ( )

Turn off JSON tracing.

Definition at line 379 of file Env.h.

◆ disable_sigs()

void ripple::test::jtx::Env::disable_sigs ( )

Turn off signature checks.

Definition at line 386 of file Env.h.

◆ memoize()

void ripple::test::jtx::Env::memoize ( Account const & account )

Associate AccountID with account.

Definition at line 156 of file Env.cpp.

◆ lookup() [1/2]

Account const & ripple::test::jtx::Env::lookup ( AccountID const & id ) const

Returns the Account given the AccountID.

Definition at line 162 of file Env.cpp.

◆ lookup() [2/2]

Account const & ripple::test::jtx::Env::lookup ( std::string const & base58ID ) const

Definition at line 174 of file Env.cpp.

◆ balance() [1/2]

PrettyAmount ripple::test::jtx::Env::balance ( Account const & account ) const

Returns the XRP balance on an account.

Returns 0 if the account does not exist.

Definition at line 183 of file Env.cpp.

◆ seq()

std::uint32_t ripple::test::jtx::Env::seq ( Account const & account ) const

Returns the next sequence number on account.

Exceptions: Throws if the account does not exist

Definition at line 207 of file Env.cpp.

◆ balance() [2/2]

PrettyAmount ripple::test::jtx::Env::balance	(	Account const &	account,
		Issue const &	issue
	)		const

Return the balance on an account.

Returns 0 if the trust line does not exist.

Definition at line 192 of file Env.cpp.

◆ le() [1/2]

std::shared_ptr< SLE const > ripple::test::jtx::Env::le ( Account const & account ) const

Return an account root.

Returns: empty if the account does not exist.

Definition at line 216 of file Env.cpp.

◆ le() [2/2]

std::shared_ptr< SLE const > ripple::test::jtx::Env::le ( Keylet const & k ) const

Return a ledger entry.

Returns: empty if the ledger entry does not exist

Definition at line 222 of file Env.cpp.

◆ jt()

template<class JsonValue , class... FN>

JTx ripple::test::jtx::Env::jt	(	JsonValue &&	jv,
		FN const &...	fN
	)

Create a JTx from parameters.

Definition at line 439 of file Env.h.

◆ json()

template<class JsonValue , class... FN>

Json::Value ripple::test::jtx::Env::json	(	JsonValue &&	jv,
		FN const &...	fN
	)

Create JSON from parameters.

This will apply funclets and autofill.

Definition at line 453 of file Env.h.

◆ require()

template<class... Args>

void ripple::test::jtx::Env::require ( Args const &... args )

Check a set of requirements.

The requirements are formed from condition functors.

Definition at line 466 of file Env.h.

◆ parseResult()

std::pair< TER, bool > ripple::test::jtx::Env::parseResult ( Json::Value const & jr )

static

Gets the TER result and didApply flag from a RPC Json result object.

Definition at line 276 of file Env.cpp.

◆ submit()

void ripple::test::jtx::Env::submit ( JTx const & jt )

virtual

Submit an existing JTx.

This calls postconditions.

Definition at line 288 of file Env.cpp.

◆ sign_and_submit()

void ripple::test::jtx::Env::sign_and_submit	(	JTx const &	jt,
		Json::Value	params = `Json::nullValue`
	)

Use the submit RPC command with a provided JTx object.

This calls postconditions.

Definition at line 311 of file Env.cpp.

◆ postconditions()

void ripple::test::jtx::Env::postconditions	(	JTx const &	jt,
		TER	ter,
		bool	didApply
	)

Check expected postconditions of JTx submission.

Definition at line 349 of file Env.cpp.

◆ apply()

template<class JsonValue , class... FN>

void ripple::test::jtx::Env::apply	(	JsonValue &&	jv,
		FN const &...	fN
	)

Apply funclets and submit.

Definition at line 498 of file Env.h.

◆ operator()()

template<class JsonValue , class... FN>

void ripple::test::jtx::Env::operator()	(	JsonValue &&	jv,
		FN const &...	fN
	)

Definition at line 505 of file Env.h.

◆ ter()

TER ripple::test::jtx::Env::ter ( ) const

Return the TER for the last JTx.

Definition at line 513 of file Env.h.

◆ meta()

std::shared_ptr< STObject const > ripple::test::jtx::Env::meta ( )

Return metadata for the last JTx.

Effects:

The open ledger is closed as if by a call
to close(). The metadata for the last
transaction ID, if any, is returned.

Definition at line 374 of file Env.cpp.

◆ tx()

std::shared_ptr< STTx const > ripple::test::jtx::Env::tx ( ) const

Return the tx data for the last JTx.

Effects:

The tx data for the last transaction
ID, if any, is returned. No side
effects.

Note: Only necessary for JTx submitted with via sign-and-submit method.

Definition at line 382 of file Env.cpp.

◆ enableFeature()

void ripple::test::jtx::Env::enableFeature ( uint256 const feature )

Definition at line 465 of file Env.cpp.

◆ disableFeature()

void ripple::test::jtx::Env::disableFeature ( uint256 const feature )

Definition at line 473 of file Env.cpp.

◆ fund() [1/2]

void ripple::test::jtx::Env::fund	(	bool	setDefaultRipple,
		STAmount const &	amount,
		Account const &	account
	)

private

Definition at line 228 of file Env.cpp.

◆ fund_arg() [1/2]

void ripple::test::jtx::Env::fund_arg	(	STAmount const &	amount,
		Account const &	account
	)

private

Definition at line 554 of file Env.h.

◆ fund_arg() [2/2]

template<std::size_t N>

void ripple::test::jtx::Env::fund_arg	(	STAmount const &	amount,
		std::array< Account, N > const &	list
	)

private

Definition at line 561 of file Env.h.

◆ fund() [2/2]

template<class Arg , class... Args>

void ripple::test::jtx::Env::fund	(	STAmount const &	amount,
		Arg const &	arg,
		Args const &...	args
	)

Create a new account with some XRP.

These convenience functions are for easy set-up of the environment, they bypass fee, seq, and sig settings. The XRP is transferred from the master account.

Preconditions: The account must not already exist

Effects: The asfDefaultRipple on the account is set, and the sequence number is incremented, unless the account is wrapped with a call to noripple.

The account's XRP balance is set to amount.

Generates a test that the balance is set.

Parameters

amount	The amount of XRP to transfer to each account.
args	A heterogeneous list of accounts to fund or calls to noripple with lists of accounts to fund.

Definition at line 596 of file Env.h.

◆ trust() [1/2]

void ripple::test::jtx::Env::trust	(	STAmount const &	amount,
		Account const &	account
	)

Establish trust lines.

These convenience functions are for easy set-up of the environment, they bypass fee, seq, and sig settings.

Preconditions: The account must already exist

Effects: A trust line is added for the account. The account's sequence number is incremented. The account is refunded for the transaction fee to set the trust line.

The refund comes from the master account.

Definition at line 259 of file Env.cpp.

◆ trust() [2/2]

template<class... Accounts>

void ripple::test::jtx::Env::trust	(	STAmount const &	amount,
		Account const &	to0,
		Account const &	to1,
		Accounts const &...	toN
	)

Definition at line 626 of file Env.h.

◆ do_rpc()

Json::Value ripple::test::jtx::Env::do_rpc	(	std::vector< std::string > const &	args,
		std::unordered_map< std::string, std::string > const &	headers = `{}`
	)

protected

Definition at line 457 of file Env.cpp.

◆ autofill_sig()

void ripple::test::jtx::Env::autofill_sig ( JTx & jt )

protected

Definition at line 388 of file Env.cpp.

◆ autofill()

void ripple::test::jtx::Env::autofill ( JTx & jt )

protectedvirtual

Definition at line 411 of file Env.cpp.

◆ st()

std::shared_ptr< STTx const > ripple::test::jtx::Env::st ( JTx const & jt )

protected

Create a STTx from a JTx The framework requires that JSON is valid.

On a parse error, the JSON is logged and an exception thrown. Throws: parse_error

Definition at line 431 of file Env.cpp.

◆ invoke() [1/2]

template<class... FN>

void ripple::test::jtx::Env::invoke	(	STTx &	stx,
		FN const &...	fN
	)

protected

Definition at line 668 of file Env.h.

◆ invoke() [2/2]

template<class... FN>

void ripple::test::jtx::Env::invoke	(	JTx &	jt,
		FN const &...	fN
	)

protected

Definition at line 676 of file Env.h.

Member Data Documentation

◆ test

beast::unit_test::suite& ripple::test::jtx::Env::test

Definition at line 119 of file Env.h.

◆ master

Account const& ripple::test::jtx::Env::master = Account::master

Definition at line 121 of file Env.h.

◆ bundle_

AppBundle ripple::test::jtx::Env::bundle_

private

Definition at line 141 of file Env.h.

◆ journal

const beast::Journal ripple::test::jtx::Env::journal

Definition at line 144 of file Env.h.

◆ trace_

int ripple::test::jtx::Env::trace_ = 0

protected

Definition at line 638 of file Env.h.

◆ stopwatch_

TestStopwatch ripple::test::jtx::Env::stopwatch_

protected

Definition at line 639 of file Env.h.

◆ txid_

uint256 ripple::test::jtx::Env::txid_

protected

Definition at line 640 of file Env.h.

◆ ter_

TER ripple::test::jtx::Env::ter_ = tesSUCCESS

protected

Definition at line 641 of file Env.h.

◆ map_

std::unordered_map<AccountID, Account> ripple::test::jtx::Env::map_

protected

Definition at line 682 of file Env.h.

Classes

Public Member Functions

Static Public Member Functions

Public Attributes

Protected Member Functions

Protected Attributes

Private Member Functions

Private Attributes

Detailed Description

Constructor & Destructor Documentation

◆ Env() [1/6]

◆ Env() [2/6]

◆ Env() [3/6]

◆ Env() [4/6]

◆ Env() [5/6]

◆ Env() [6/6]

◆ ~Env()

Member Function Documentation

◆ operator=()

◆ app() [1/2]

◆ app() [2/2]

◆ timeKeeper()

◆ now()

◆ client()

◆ rpc() [1/2]

◆ rpc() [2/2]

◆ current()

◆ closed()

◆ close() [1/3]

◆ close() [2/3]

◆ close() [3/3]

◆ trace()

◆ notrace()

◆ disable_sigs()

◆ memoize()

◆ lookup() [1/2]

◆ lookup() [2/2]

◆ balance() [1/2]

◆ seq()

◆ balance() [2/2]

◆ le() [1/2]

◆ le() [2/2]

◆ jt()

◆ json()

◆ require()

◆ parseResult()

◆ submit()

◆ sign_and_submit()

◆ postconditions()

◆ apply()

◆ operator()()

◆ ter()

◆ meta()

◆ tx()

◆ enableFeature()

◆ disableFeature()

◆ fund() [1/2]

◆ fund_arg() [1/2]

◆ fund_arg() [2/2]

◆ fund() [2/2]

◆ trust() [1/2]

◆ trust() [2/2]

◆ do_rpc()

◆ autofill_sig()

◆ autofill()

◆ st()

◆ invoke() [1/2]

◆ invoke() [2/2]

Member Data Documentation

◆ test

◆ master

◆ bundle_

◆ journal

◆ trace_

◆ stopwatch_

◆ txid_

◆ ter_

◆ map_