ExternalVendorCode/corda
1
0
Fork 0
mirror of https://github.com/corda/corda.git synced 2025-02-20 09:26:41 +00:00
Code Issues Actions 2 Packages Projects Releases Wiki Activity

testdsl: Javadoc comments

Browse Source
This commit is contained in:
Andras Slemmer 2016-07-07 13:47:47 +01:00
parent 3d885eb928
commit cd0299f650
7 changed files with 216 additions and 83 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

32
contracts/src/main/kotlin/com/r3corda/contracts/testing/TestUtils.kt
View File

@ -18,38 +18,6 @@ import java.security.PublicKey
import java.time.Instant
import java.util.*
// In a real system this would be a persistent map of hash to bytecode and we'd instantiate the object as needed inside
// a sandbox. For unit tests we just have a hard-coded list.
val TEST_PROGRAM_MAP: Map<Contract, Class<out Contract>> = mapOf(
CASH_PROGRAM_ID to Cash::class.java,
CP_PROGRAM_ID to CommercialPaper::class.java,
JavaCommercialPaper.JCP_PROGRAM_ID to JavaCommercialPaper::class.java,
DUMMY_PROGRAM_ID to DummyContract::class.java,
IRS_PROGRAM_ID to InterestRateSwap::class.java
)
fun generateState() = DummyState(Random().nextInt())
////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
//
// Defines a simple DSL for building pseudo-transactions (not the same as the wire protocol) for testing purposes.
//
// Define a transaction like this:
//
// transaction {
// input { someExpression }
// output { someExpression }
// arg { someExpression }
//
// tweak {
// ... same thing but works with a copy of the parent, can add inputs/outputs/args just within this scope.
// }
//
// contract.accepts() -> should pass
// contract `fails requirement` "some substring of the error message"
// }
// For Java compatibility please define helper methods here and then define the infix notation
object JavaTestHelpers {
@JvmStatic fun ownedBy(state: Cash.State, owner: PublicKey) = state.copy(owner = owner)
@JvmStatic fun issuedBy(state: Cash.State, party: Party) = state.copy(amount = Amount(state.amount.quantity, state.issuanceDef.copy(issuer = state.deposit.copy(party = party))))

2
core/src/main/kotlin/com/r3corda/core/crypto/CryptoUtilities.kt
View File

@ -169,4 +169,4 @@ operator fun KeyPair.component1() = this.private
operator fun KeyPair.component2() = this.public
/** A simple wrapper that will make it easier to swap out the EC algorithm we use in future */
fun generateKeyPair() = EddsaKeyPairGenerator().generateKeyPair()
fun generateKeyPair() = EddsaKeyPairGenerator().generateKeyPair()!!

73
core/src/main/kotlin/com/r3corda/core/testing/LedgerDSLInterpreter.kt
View File

@ -4,42 +4,105 @@ import com.r3corda.core.contracts.*
import com.r3corda.core.crypto.SecureHash
import java.io.InputStream
/**
* This interface defines output state lookup by label. It is split from the interpreter interfaces so that outputs may
* be looked up both in ledger{..} and transaction{..} blocks.
*/
interface OutputStateLookup {
/**
* Retrieves an output previously defined by [TransactionDSLInterpreter._output] with a label passed in.
* @param clazz: The class object holding the type of the output state expected.
* @param label: The label of the to-be-retrieved output state
* @return: The output [StateAndRef]
*/
fun <S : ContractState> retrieveOutputStateAndRef(clazz: Class<S>, label: String): StateAndRef<S>
}
/**
* This interface defines the bare bone functionality that a Ledger DSL interpreter should implement.
*
* TODO (Kotlin 1.1): Use type synonyms to make the type params less unwieldy
*/
interface LedgerDSLInterpreter<R, out T : TransactionDSLInterpreter<R>> : OutputStateLookup {
/**
* Creates and adds a transaction to the ledger.
* @param transactionLabel: Optional label of the transaction, to be used in diagnostic messages.
* @param transactionBuilder: The base transactionBuilder that will be used to build the transaction.
* @param dsl: The dsl that should be interpreted for building the transaction.
* @return: The final [WireTransaction] of the built transaction.
*/
fun _transaction(transactionLabel: String?, transactionBuilder: TransactionBuilder,
dsl: TransactionDSL<R, T>.() -> R): WireTransaction
/**
* Creates and adds a transaction to the ledger that will not be verified by [verifies].
* @param transactionLabel: Optional label of the transaction, to be used in diagnostic messages.
* @param transactionBuilder: The base transactionBuilder that will be used to build the transaction.
* @param dsl: The dsl that should be interpreted for building the transaction.
* @return: The final [WireTransaction] of the built transaction.
*/
fun _unverifiedTransaction(transactionLabel: String?, transactionBuilder: TransactionBuilder,
dsl: TransactionDSL<R, T>.() -> Unit): WireTransaction
/**
* Creates a local scoped copy of the ledger.
* @param dsl: The ledger DSL to be interpreted using the copy.
*/
fun tweak(dsl: LedgerDSL<R, T, LedgerDSLInterpreter<R, T>>.() -> Unit)
/**
* Adds an attachment to the ledger.
* @param attachment: The [InputStream] defining the contents of the attachment.
* @return: The [SecureHash] that identifies the attachment, to be used in transactions.
*/
fun attachment(attachment: InputStream): SecureHash
/**
* Verifies the ledger using [TransactionGroup.verify], throws if the verification fails.
*/
fun verifies()
}
/**
* This is the class the top-level primitives deal with. It delegates all other primitives to the contained interpreter.
* This way we have a decoupling of the DSL "AST" and the interpretation(s) of it. Note how the delegation forces
* covariance of the TransactionInterpreter parameter.
*
* TODO (Kotlin 1.1): Use type synonyms to make the type params less unwieldy
* This is the class that defines the syntactic sugar of the ledger Test DSL and delegates to the contained interpreter,
* and what is actually used in `ledger { (...) }`. Add convenience functions here, or if you want to extend the DSL
* functionality then first add your primitive to [LedgerDSLInterpreter] and then add the convenience defaults/extension
* methods here.
*/
class LedgerDSL<R, out T : TransactionDSLInterpreter<R>, out L : LedgerDSLInterpreter<R, T>> (val interpreter: L) :
LedgerDSLInterpreter<R, TransactionDSLInterpreter<R>> by interpreter {
/**
* @see LedgerDSLInterpreter._transaction
*/
@JvmOverloads
fun transaction(label: String? = null, transactionBuilder: TransactionBuilder = TransactionBuilder(),
dsl: TransactionDSL<R, TransactionDSLInterpreter<R>>.() -> R) =
_transaction(label, transactionBuilder, dsl)
/**
* @see LedgerDSLInterpreter._unverifiedTransaction
*/
@JvmOverloads
fun unverifiedTransaction(label: String? = null, transactionBuilder: TransactionBuilder = TransactionBuilder(),
dsl: TransactionDSL<R, TransactionDSLInterpreter<R>>.() -> Unit) =
_unverifiedTransaction(label, transactionBuilder, dsl)
/**
* @see OutputStateLookup.retrieveOutputStateAndRef
*/
inline fun <reified S : ContractState> String.outputStateAndRef(): StateAndRef<S> =
retrieveOutputStateAndRef(S::class.java, this)
/**
* Retrieves the output [TransactionState] based on the label.
* @see OutputStateLookup.retrieveOutputStateAndRef
*/
inline fun <reified S : ContractState> String.output(): TransactionState<S> =
outputStateAndRef<S>().state
/**
* Retrieves the output [StateRef] based on the label.
* @see OutputStateLookup.retrieveOutputStateAndRef
*/
fun String.outputRef(): StateRef = outputStateAndRef<ContractState>().ref
}

57
core/src/main/kotlin/com/r3corda/core/testing/TestDSL.kt
View File

@ -14,6 +14,36 @@ import java.security.KeyPair
import java.security.PublicKey
import java.util.*
////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
//
// Here is a simple DSL for building pseudo-transactions (not the same as the wire protocol) for testing purposes.
//
// Define a transaction like this:
//
// ledger {
// transaction {
// input { someExpression }
// output { someExpression }
// command { someExpression }
//
// tweak {
// ... same thing but works with a copy of the parent, can add inputs/outputs/commands just within this scope.
// }
//
// contract.verifies() -> verify() should pass
// contract `fails with` "some substring of the error message"
// }
// }
//
/**
* Here follows implementations of the [LedgerDSLInterpreter] and [TransactionDSLInterpreter] interfaces to be used in
* tests. Top level primitives [ledger] and [transaction] that bind the interpreter types are also defined here.
*/
/**
* @see JavaTestHelpers.transaction
*/
fun transaction(
transactionLabel: String? = null,
transactionBuilder: TransactionBuilder = TransactionBuilder(),
@ -23,6 +53,9 @@ fun transaction(
>.() -> EnforceVerifyOrFail
) = JavaTestHelpers.transaction(transactionLabel, transactionBuilder, dsl)
/**
* @see JavaTestHelpers.ledger
*/
fun ledger(
identityService: IdentityService = MOCK_IDENTITY_SERVICE,
storageService: StorageService = MockStorageService(),
@ -70,6 +103,7 @@ sealed class EnforceVerifyOrFail {
}
class DuplicateOutputLabel(label: String) : Exception("Output label '$label' already used")
class AttachmentResolutionException(attachmentId: SecureHash) : Exception("Attachment with id $attachmentId not found")
/**
* This interpreter builds a transaction, and [TransactionDSL.verifies] that the resolved transaction is correct. Note
@ -83,7 +117,7 @@ data class TestTransactionDSLInterpreter private constructor(
constructor(
ledgerInterpreter: TestLedgerDSLInterpreter,
transactionBuilder: TransactionBuilder // = TransactionBuilder()
transactionBuilder: TransactionBuilder
) : this(ledgerInterpreter, transactionBuilder, HashMap())
private fun copy(): TestTransactionDSLInterpreter =
@ -161,9 +195,6 @@ data class TestTransactionDSLInterpreter private constructor(
) = dsl(TransactionDSL(copy()))
}
class AttachmentResolutionException(attachmentId: SecureHash) :
Exception("Attachment with id $attachmentId not found")
data class TestLedgerDSLInterpreter private constructor (
private val identityService: IdentityService,
private val storageService: StorageService,
@ -241,9 +272,9 @@ data class TestLedgerDSLInterpreter private constructor (
internal fun resolveAttachment(attachmentId: SecureHash): Attachment =
storageService.attachments.openAttachment(attachmentId) ?: throw AttachmentResolutionException(attachmentId)
private fun <Return> interpretTransactionDsl(
private fun <R> interpretTransactionDsl(
transactionBuilder: TransactionBuilder,
dsl: TransactionDSL<EnforceVerifyOrFail, TestTransactionDSLInterpreter>.() -> Return
dsl: TransactionDSL<EnforceVerifyOrFail, TestTransactionDSLInterpreter>.() -> R
): TestTransactionDSLInterpreter {
val transactionInterpreter = TestTransactionDSLInterpreter(this, transactionBuilder)
dsl(TransactionDSL(transactionInterpreter))
@ -339,6 +370,12 @@ data class TestLedgerDSLInterpreter private constructor (
}
}
/**
* Signs all transactions passed in.
* @param transactionsToSign: Transactions to be signed.
* @param extraKeys: extra keys to sign transactions with.
* @return: List of [SignedTransaction]s.
*/
fun signAll(transactionsToSign: List<WireTransaction>, extraKeys: Array<out KeyPair>) = transactionsToSign.map { wtx ->
val allPubKeys = wtx.signers.toMutableSet()
val bits = wtx.serialize()
@ -353,6 +390,10 @@ fun signAll(transactionsToSign: List<WireTransaction>, extraKeys: Array<out KeyP
SignedTransaction(bits, signatures)
}
/**
* Signs all transactions in the ledger.
* @param extraKeys: extra keys to sign transactions with.
* @return: List of [SignedTransaction]s.
*/
fun LedgerDSL<EnforceVerifyOrFail, TestTransactionDSLInterpreter, TestLedgerDSLInterpreter>.signAll(
transactionsToSign: List<WireTransaction> = this.interpreter.wireTransactions, vararg extraKeys: KeyPair) =
signAll(transactionsToSign, extraKeys)
vararg extraKeys: KeyPair) = signAll(this.interpreter.wireTransactions, extraKeys)

10
core/src/main/kotlin/com/r3corda/core/testing/TestUtils.kt
View File

@ -88,6 +88,12 @@ object JavaTestHelpers {
return HostAndPort.fromParts("localhost", freePort)
}
/**
* Creates and tests a ledger built by the passed in dsl.
* @param identityService: The [IdentityService] to be used while building the ledger.
* @param storageService: The [StorageService] to be used for storing e.g. [Attachment]s.
* @param dsl: The dsl building the ledger.
*/
@JvmStatic @JvmOverloads fun ledger(
identityService: IdentityService = MOCK_IDENTITY_SERVICE,
storageService: StorageService = MockStorageService(),
@ -98,6 +104,10 @@ object JavaTestHelpers {
return ledgerDsl
}
/**
* Creates a ledger with a single transaction, built by the passed in dsl.
* @see LedgerDSLInterpreter._transaction
*/
@JvmStatic @JvmOverloads fun transaction(
transactionLabel: String? = null,
transactionBuilder: TransactionBuilder = TransactionBuilder(),

123
core/src/main/kotlin/com/r3corda/core/testing/TransactionDSLInterpreter.kt
View File

@ -5,58 +5,79 @@ import com.r3corda.core.crypto.Party
import com.r3corda.core.crypto.SecureHash
import com.r3corda.core.seconds
import java.security.PublicKey
import java.time.Duration
import java.time.Instant
////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
//
// Defines a simple DSL for building pseudo-transactions (not the same as the wire protocol) for testing purposes.
//
// Define a transaction like this:
//
// ledger {
// transaction {
// input { someExpression }
// output { someExpression }
// command { someExpression }
//
// tweak {
// ... same thing but works with a copy of the parent, can add inputs/outputs/commands just within this scope.
// }
//
// contract.verifies() -> verify() should pass
// contract `fails with` "some substring of the error message"
// }
// }
//
/**
* The [TransactionDSLInterpreter] defines the interface DSL interpreters should satisfy. No
* overloading/default valuing should be done here, only the basic functions that are required to implement everything.
* Same goes for functions requiring reflection e.g. [OutputStateLookup.retrieveOutputStateAndRef]
* Put convenience functions in [TransactionDSL] instead. There are some cases where the overloads would clash with the
* Interpreter interface, in these cases define a "backing" function in the interface instead (e.g. [_command]).
*
* This way the responsibility of providing a nice frontend DSL and the implementation(s) are separated.
* This interface defines the bare bone functionality that a Transaction DSL interpreter should implement.
* @param <R>: The return type of [verifies]/[failsWith] and the like. It is generic so that we have control over whether
* we want to enforce users to call these methods (@see [EnforceVerifyOrFail]) or not.
*/
interface TransactionDSLInterpreter<R> : OutputStateLookup {
/**
* A reference to the enclosing ledger{..}'s interpreter.
*/
val ledgerInterpreter: LedgerDSLInterpreter<R, TransactionDSLInterpreter<R>>
/**
* Adds an input reference to the transaction. Note that [verifies] will resolve this reference.
* @param stateRef: The input [StateRef].
*/
fun input(stateRef: StateRef)
/**
* Adds an output to the transaction.
* @param label: An optional label that may be later used to retrieve the output probably in other transactions.
* @param notary: The associated notary.
* @param contractState: The state itself.
*/
fun _output(label: String?, notary: Party, contractState: ContractState)
/**
* Adds an [Attachment] reference to the transaction.
* @param attachmentId: The hash of the attachment, possibly returned by [LedgerDSLInterpreter.attachment]
*/
fun attachment(attachmentId: SecureHash)
/**
* Adds a command to the transaction.
* @param signers: The signer public keys.
* @param commandData: The contents of the command.
*/
fun _command(signers: List<PublicKey>, commandData: CommandData)
/**
* Verifies the transaction.
* @return: Possibly a token confirming that [verifies] has been called.
*/
fun verifies(): R
/**
* Verifies the transaction, expecting an exception to be thrown.
* @param expectedMessage: An optional string to be searched for in the raised exception.
*/
fun failsWith(expectedMessage: String?): R
fun tweak(
dsl: TransactionDSL<R, TransactionDSLInterpreter<R>>.() -> R
): R
/**
* Creates a local scoped copy of the transaction.
* @param dsl: The transaction DSL to be interpreted using the copy.
*/
fun tweak(dsl: TransactionDSL<R, TransactionDSLInterpreter<R>>.() -> R): R
}
class TransactionDSL<R, out T : TransactionDSLInterpreter<R>> (val interpreter: T) :
TransactionDSLInterpreter<R> by interpreter {
fun input(stateLabel: String) = input(retrieveOutputStateAndRef(ContractState::class.java, stateLabel).ref)
/**
* Adds the passed in state as a non-verified transaction output to the ledger and adds that as an input.
* Looks up the output label and adds the found state as an input.
* @param stateLabel: The label of the output state specified when calling [LedgerDSLInterpreter._output] and friends.
*/
fun input(stateLabel: String) = input(retrieveOutputStateAndRef(ContractState::class.java, stateLabel).ref)
/**
* Creates an [LedgerDSLInterpreter._unverifiedTransaction] with a single output state and adds it's reference as an
* input to the current transaction.
* @param state: The state to be added.
*/
fun input(state: ContractState) {
val transaction = ledgerInterpreter._unverifiedTransaction(null, TransactionBuilder()) {
@ -66,23 +87,53 @@ class TransactionDSL<R, out T : TransactionDSLInterpreter<R>> (val interpreter:
}
fun input(stateClosure: () -> ContractState) = input(stateClosure())
/**
* @see TransactionDSLInterpreter._output
*/
@JvmOverloads
fun output(label: String? = null, notary: Party = DUMMY_NOTARY, contractStateClosure: () -> ContractState) =
_output(label, notary, contractStateClosure())
/**
* @see TransactionDSLInterpreter._output
*/
@JvmOverloads
fun output(label: String? = null, contractState: ContractState) =
_output(label, DUMMY_NOTARY, contractState)
/**
* @see TransactionDSLInterpreter._command
*/
fun command(vararg signers: PublicKey, commandDataClosure: () -> CommandData) =
_command(listOf(*signers), commandDataClosure())
/**
* @see TransactionDSLInterpreter._command
*/
fun command(signer: PublicKey, commandData: CommandData) = _command(listOf(signer), commandData)
/**
* Adds a timestamp command to the transaction.
* @param time: The [Instant] of the [TimestampCommand].
* @param tolerance: The tolerance of the [TimestampCommand].
* @param notary: The notary to sign the command.
*/
@JvmOverloads
fun timestamp(time: Instant, notary: PublicKey = DUMMY_NOTARY.owningKey) =
timestamp(TimestampCommand(time, 30.seconds), notary)
fun timestamp(time: Instant, tolerance: Duration = 30.seconds, notary: PublicKey = DUMMY_NOTARY.owningKey) =
timestamp(TimestampCommand(time, tolerance), notary)
/**
* Adds a timestamp command to the transaction.
* @param data: The [TimestampCommand].
* @param notary: The notary to sign the command.
*/
@JvmOverloads
fun timestamp(data: TimestampCommand, notary: PublicKey = DUMMY_NOTARY.owningKey) = command(notary, data)
/**
* Asserts that the transaction will fail verification
*/
fun fails() = failsWith(null)
/**
* @see TransactionDSLInterpreter.failsWith
*/
infix fun `fails with`(msg: String) = failsWith(msg)
}

2
node/src/test/kotlin/com/r3corda/node/messaging/TwoPartyTradeProtocolTests.kt
View File

@ -484,7 +484,7 @@ class TwoPartyTradeProtocolTests {
}
command(MEGA_CORP_PUBKEY) { CommercialPaper.Commands.Issue() }
if (!withError)
command(notary.owningKey) { TimestampCommand(TEST_TX_TIME, 30.seconds) }
timestamp(time = TEST_TX_TIME, notary = notary.owningKey)
if (attachmentID != null)
attachment(attachmentID)
if (withError) {