corda/docs/source/tutorial-test-dsl.rst

Writing a contract test

This tutorial will take you through the steps required to write a contract test using Kotlin and Java.

The testing DSL allows one to define a piece of the ledger with transactions referring to each other, and ways of verifying their correctness.

Testing single transactions

We start with the empty ledger:

class CommercialPaperTest{
    @Test
    fun emptyLedger() {
        ledger {
        }
    }
    ...
}

import static net.corda.core.testing.JavaTestHelpers.*;
import static net.corda.core.contracts.JavaTestHelpers.*;

@Test
public void emptyLedger() {
    ledger(l -> {
        return Unit.INSTANCE; // We need to return this explicitly
    });
}

The DSL keyword ledger takes a closure that can build up several transactions and may verify their overall correctness. A ledger is effectively a fresh world with no pre-existing transactions or services within it.

We will start with defining helper function that returns a CommercialPaper state:

fun getPaper(): ICommercialPaperState = CommercialPaper.State(
    issuance = MEGA_CORP.ref(123),
    owner = MEGA_CORP_PUBKEY,
    faceValue = 1000.DOLLARS `issued by` MEGA_CORP.ref(123),
    maturityDate = TEST_TX_TIME + 7.days
)

private final OpaqueBytes defaultRef = new OpaqueBytes(new byte[]{123});

private ICommercialPaperState getPaper() {
    return new JavaCommercialPaper.State(
        getMEGA_CORP().ref(defaultRef),
        getMEGA_CORP_PUBKEY(),
        issuedBy(DOLLARS(1000), getMEGA_CORP().ref(defaultRef)),
        getTEST_TX_TIME().plus(7, ChronoUnit.DAYS)
    );
}

It's a CommercialPaper issued by MEGA_CORP with face value of $1000 and maturity date in 7 days.

Let's add a CommercialPaper transaction:

@Test
fun simpleCPDoesntCompile() {
    val inState = getPaper()
    ledger {
        transaction {
            input(inState)
        }
    }
}

@Test
public void simpleCPDoesntCompile() {
    ICommercialPaperState inState = getPaper();
    ledger(l -> {
        l.transaction(tx -> {
            tx.input(inState);
        });
        return Unit.INSTANCE;
    });
}

We can add a transaction to the ledger using the transaction primitive. The transaction in turn may be defined by specifying input-s, output-s, command-s and attachment-s.

The above input call is a bit special; transactions don't actually contain input states, just references to output states of other transactions. Under the hood the above input call creates a dummy transaction in the ledger (that won't be verified) which outputs the specified state, and references that from this transaction.

The above code however doesn't compile:

Error:(29, 17) Kotlin: Type mismatch: inferred type is Unit but EnforceVerifyOrFail was expected

Error:(35, 27) java: incompatible types: bad return type in lambda expression missing return value

This is deliberate: The DSL forces us to specify either this.verifies() or this `fails with` "some text" on the last line of transaction:

@Test
fun simpleCP() {
    val inState = getPaper()
    ledger {
        transaction {
            input(inState)
            this.verifies()
        }
    }
}

@Test
public void simpleCP() {
    ICommercialPaperState inState = getPaper();
    ledger(l -> {
        l.transaction(tx -> {
            tx.input(inState);
            return tx.verifies();
        });
        return Unit.INSTANCE;
    });
}

Let's take a look at a transaction that fails.

@Test
fun simpleCPMove() {
    val inState = getPaper()
    ledger {
        transaction {
            input(inState)
            command(MEGA_CORP_PUBKEY) { CommercialPaper.Commands.Move() }
            this.verifies()
        }
    }
}

@Test
public void simpleCPMove() {
    ICommercialPaperState inState = getPaper();
    ledger(l -> {
        l.transaction(tx -> {
            tx.input(inState);
            tx.command(getMEGA_CORP_PUBKEY(), new JavaCommercialPaper.Commands.Move());
            return tx.verifies();
        });
        return Unit.INSTANCE;
    });
}

When run, that code produces the following error:

net.corda.core.contracts.TransactionVerificationException$ContractRejection: java.lang.IllegalArgumentException: Failed requirement: the state is propagated

net.corda.core.contracts.TransactionVerificationException$ContractRejection: java.lang.IllegalStateException: the state is propagated

The transaction verification failed, because we wanted to move paper but didn't specify an output - but the state should be propagated. However we can specify that this is an intended behaviour by changing this.verifies() to this `fails with` "the state is propagated":

@Test
fun simpleCPMoveFails() {
    val inState = getPaper()
    ledger {
        transaction {
            input(inState)
            command(MEGA_CORP_PUBKEY) { CommercialPaper.Commands.Move() }
            this `fails with` "the state is propagated"
        }
    }
}

@Test
public void simpleCPMoveFails() {
    ICommercialPaperState inState = getPaper();
    ledger(l -> {
        l.transaction(tx -> {
            tx.input(inState);
            tx.command(getMEGA_CORP_PUBKEY(), new JavaCommercialPaper.Commands.Move());
            return tx.failsWith("the state is propagated");
        });
        return Unit.INSTANCE;
    });
}

We can continue to build the transaction until it verifies:

@Test
fun simpleCPMoveSuccess() {
    val inState = getPaper()
    ledger {
        transaction {
            input(inState)
            command(MEGA_CORP_PUBKEY) { CommercialPaper.Commands.Move() }
            this `fails with` "the state is propagated"
            output("alice's paper") { inState `owned by` ALICE_PUBKEY }
            this.verifies()
        }
    }
}

@Test
public void simpleCPMoveSuccess() {
    ICommercialPaperState inState = getPaper();
    ledger(l -> {
        l.transaction(tx -> {
            tx.input(inState);
            tx.command(getMEGA_CORP_PUBKEY(), new JavaCommercialPaper.Commands.Move());
            tx.failsWith("the state is propagated");
            tx.output("alice's paper", inState.withOwner(getALICE_PUBKEY()));
            return tx.verifies();
        });
        return Unit.INSTANCE;
    });
}

output specifies that we want the input state to be transferred to ALICE and command adds the Move command itself, signed by the current owner of the input state, MEGA_CORP_PUBKEY.

We constructed a complete signed commercial paper transaction and verified it. Note how we left in the fails with line - this is fine, the failure will be tested on the partially constructed transaction.

What should we do if we wanted to test what happens when the wrong party signs the transaction? If we simply add a command it will permanently ruin the transaction... Enter tweak:

@Test
fun `simple issuance with tweak`() {
    ledger {
        transaction {
            output("paper") { getPaper() } // Some CP is issued onto the ledger by MegaCorp.
            tweak {
                command(DUMMY_PUBKEY_1) { CommercialPaper.Commands.Issue() }
                timestamp(TEST_TX_TIME)
                this `fails with` "output states are issued by a command signer"
            }
            command(MEGA_CORP_PUBKEY) { CommercialPaper.Commands.Issue() }
            timestamp(TEST_TX_TIME)
            this.verifies()
        }
    }
}

@Test
public void simpleIssuanceWithTweak() {
    ledger(l -> {
        l.transaction(tx -> {
            tx.output("paper", getPaper()); // Some CP is issued onto the ledger by MegaCorp.
            tx.tweak(tw -> {
                tw.command(getDUMMY_PUBKEY_1(), new JavaCommercialPaper.Commands.Issue());
                tw.timestamp(getTEST_TX_TIME());
                return tw.failsWith("output states are issued by a command signer");
            });
            tx.command(getMEGA_CORP_PUBKEY(), new JavaCommercialPaper.Commands.Issue());
            tx.timestamp(getTEST_TX_TIME());
            return tx.verifies();
        });
        return Unit.INSTANCE;
    });
}

tweak creates a local copy of the transaction. This makes possible to locally "ruin" the transaction while not modifying the original one, allowing testing of different error conditions.

We now have a neat little test that tests a single transaction. This is already useful, and in fact testing of a single transaction in this way is very common. There is even a shorthand top-level transaction primitive that creates a ledger with a single transaction:

@Test
fun `simple issuance with tweak and top level transaction`() {
    transaction {
        output("paper") { getPaper() } // Some CP is issued onto the ledger by MegaCorp.
        tweak {
            command(DUMMY_PUBKEY_1) { CommercialPaper.Commands.Issue() }
            timestamp(TEST_TX_TIME)
            this `fails with` "output states are issued by a command signer"
        }
        command(MEGA_CORP_PUBKEY) { CommercialPaper.Commands.Issue() }
        timestamp(TEST_TX_TIME)
        this.verifies()
    }
}

@Test
public void simpleIssuanceWithTweakTopLevelTx() {
    transaction(tx -> {
        tx.output("paper", getPaper()); // Some CP is issued onto the ledger by MegaCorp.
        tx.tweak(tw -> {
            tw.command(getDUMMY_PUBKEY_1(), new JavaCommercialPaper.Commands.Issue());
            tw.timestamp(getTEST_TX_TIME());
            return tw.failsWith("output states are issued by a command signer");
        });
        tx.command(getMEGA_CORP_PUBKEY(), new JavaCommercialPaper.Commands.Issue());
        tx.timestamp(getTEST_TX_TIME());
        return tx.verifies();
    });
}

Chaining transactions

Now that we know how to define a single transaction, let's look at how to define a chain of them:

@Test
fun `chain commercial paper`() {
    val issuer = MEGA_CORP.ref(123)

    ledger {
        unverifiedTransaction {
            output("alice's $900", 900.DOLLARS.CASH `issued by` issuer `owned by` ALICE_PUBKEY)
        }

        // Some CP is issued onto the ledger by MegaCorp.
        transaction("Issuance") {
            output("paper") { getPaper() }
            command(MEGA_CORP_PUBKEY) { CommercialPaper.Commands.Issue() }
            timestamp(TEST_TX_TIME)
            this.verifies()
        }


        transaction("Trade") {
            input("paper")
            input("alice's $900")
            output("borrowed $900") { 900.DOLLARS.CASH `issued by` issuer `owned by` MEGA_CORP_PUBKEY }
            output("alice's paper") { "paper".output<ICommercialPaperState>() `owned by` ALICE_PUBKEY }
            command(ALICE_PUBKEY) { Cash.Commands.Move() }
            command(MEGA_CORP_PUBKEY) { CommercialPaper.Commands.Move() }
            this.verifies()
        }
    }
}

@Test
public void chainCommercialPaper() {
    PartyAndReference issuer = getMEGA_CORP().ref(defaultRef);
    ledger(l -> {
        l.unverifiedTransaction(tx -> {
                    tx.output("alice's $900",
                            new Cash.State(issuedBy(DOLLARS(900), issuer), getALICE_PUBKEY(), null));
                    return Unit.INSTANCE;
                });

        // Some CP is issued onto the ledger by MegaCorp.
        l.transaction("Issuance", tx -> {
            tx.output("paper", getPaper());
            tx.command(getMEGA_CORP_PUBKEY(), new JavaCommercialPaper.Commands.Issue());
            tx.timestamp(getTEST_TX_TIME());
            return tx.verifies();
        });

        l.transaction("Trade", tx -> {
            tx.input("paper");
            tx.input("alice's $900");
            tx.output("borrowed $900", new Cash.State(issuedBy(DOLLARS(900), issuer), getMEGA_CORP_PUBKEY(), null));
            JavaCommercialPaper.State inputPaper = l.retrieveOutput(JavaCommercialPaper.State.class, "paper");
            tx.output("alice's paper", inputPaper.withOwner(getALICE_PUBKEY()));
            tx.command(getALICE_PUBKEY(), new Cash.Commands.Move());
            tx.command(getMEGA_CORP_PUBKEY(), new JavaCommercialPaper.Commands.Move());
            return tx.verifies();
        });
        return Unit.INSTANCE;
    });
}

In this example we declare that ALICE has $900 but we don't care where from. For this we can use unverifiedTransaction. Note how we don't need to specify this.verifies().

Notice that we labelled output with "alice's $900", also in transaction named "Issuance" we labelled a commercial paper with "paper". Now we can subsequently refer to them in other transactions, e.g. by input("alice's $900") or "paper".output<ICommercialPaperState>().

The last transaction named "Trade" exemplifies simple fact of selling the CommercialPaper to Alice for her $900, $100 less than the face value at 10% interest after only 7 days.

We can also test whole ledger calling this.verifies() and this.fails() on the ledger level. To do so let's create a simple example that uses the same input twice:

@Test
fun `chain commercial paper double spend`() {
    val issuer = MEGA_CORP.ref(123)
    ledger {
        unverifiedTransaction {
            output("alice's $900", 900.DOLLARS.CASH `issued by` issuer `owned by` ALICE_PUBKEY)
        }

        // Some CP is issued onto the ledger by MegaCorp.
        transaction("Issuance") {
            output("paper") { getPaper() }
            command(MEGA_CORP_PUBKEY) { CommercialPaper.Commands.Issue() }
            timestamp(TEST_TX_TIME)
            this.verifies()
        }

        transaction("Trade") {
            input("paper")
            input("alice's $900")
            output("borrowed $900") { 900.DOLLARS.CASH `issued by` issuer `owned by` MEGA_CORP_PUBKEY }
            output("alice's paper") { "paper".output<ICommercialPaperState>() `owned by` ALICE_PUBKEY }
            command(ALICE_PUBKEY) { Cash.Commands.Move() }
            command(MEGA_CORP_PUBKEY) { CommercialPaper.Commands.Move() }
            this.verifies()
        }

        transaction {
            input("paper")
            // We moved a paper to another pubkey.
            output("bob's paper") { "paper".output<ICommercialPaperState>() `owned by` BOB_PUBKEY }
            command(MEGA_CORP_PUBKEY) { CommercialPaper.Commands.Move() }
            this.verifies()
        }

        this.fails()
    }
}

@Test
public void chainCommercialPaperDoubleSpend() {
    PartyAndReference issuer = getMEGA_CORP().ref(defaultRef);
    ledger(l -> {
        l.unverifiedTransaction(tx -> {
            tx.output("alice's $900",
                    new Cash.State(issuedBy(DOLLARS(900), issuer), getALICE_PUBKEY(), null));
            return Unit.INSTANCE;
        });

        // Some CP is issued onto the ledger by MegaCorp.
        l.transaction("Issuance", tx -> {
            tx.output("paper", getPaper());
            tx.command(getMEGA_CORP_PUBKEY(), new JavaCommercialPaper.Commands.Issue());
            tx.timestamp(getTEST_TX_TIME());
            return tx.verifies();
        });

        l.transaction("Trade", tx -> {
            tx.input("paper");
            tx.input("alice's $900");
            tx.output("borrowed $900", new Cash.State(issuedBy(DOLLARS(900), issuer), getMEGA_CORP_PUBKEY(), null));
            JavaCommercialPaper.State inputPaper = l.retrieveOutput(JavaCommercialPaper.State.class, "paper");
            tx.output("alice's paper", inputPaper.withOwner(getALICE_PUBKEY()));
            tx.command(getALICE_PUBKEY(), new Cash.Commands.Move());
            tx.command(getMEGA_CORP_PUBKEY(), new JavaCommercialPaper.Commands.Move());
            return tx.verifies();
        });

        l.transaction(tx -> {
            tx.input("paper");
            JavaCommercialPaper.State inputPaper = l.retrieveOutput(JavaCommercialPaper.State.class, "paper");
            // We moved a paper to other pubkey.
            tx.output("bob's paper", inputPaper.withOwner(getBOB_PUBKEY()));
            tx.command(getMEGA_CORP_PUBKEY(), new JavaCommercialPaper.Commands.Move());
            return tx.verifies();
        });
        l.fails();
        return Unit.INSTANCE;
    });
}

The transactions verifies() individually, however the state was spent twice! That's why we need the global ledger verification (this.fails() at the end). As in previous examples we can use tweak to create a local copy of the whole ledger:

@Test
fun `chain commercial tweak`() {
    val issuer = MEGA_CORP.ref(123)
    ledger {
        unverifiedTransaction {
            output("alice's $900", 900.DOLLARS.CASH `issued by` issuer `owned by` ALICE_PUBKEY)
        }

        // Some CP is issued onto the ledger by MegaCorp.
        transaction("Issuance") {
            output("paper") { getPaper() }
            command(MEGA_CORP_PUBKEY) { CommercialPaper.Commands.Issue() }
            timestamp(TEST_TX_TIME)
            this.verifies()
        }

        transaction("Trade") {
            input("paper")
            input("alice's $900")
            output("borrowed $900") { 900.DOLLARS.CASH `issued by` issuer `owned by` MEGA_CORP_PUBKEY }
            output("alice's paper") { "paper".output<ICommercialPaperState>() `owned by` ALICE_PUBKEY }
            command(ALICE_PUBKEY) { Cash.Commands.Move() }
            command(MEGA_CORP_PUBKEY) { CommercialPaper.Commands.Move() }
            this.verifies()
        }

        tweak {
            transaction {
                input("paper")
                // We moved a paper to another pubkey.
                output("bob's paper") { "paper".output<ICommercialPaperState>() `owned by` BOB_PUBKEY }
                command(MEGA_CORP_PUBKEY) { CommercialPaper.Commands.Move() }
                this.verifies()
            }
            this.fails()
        }

        this.verifies()
    }
}

@Test
public void chainCommercialPaperTweak() {
    PartyAndReference issuer = getMEGA_CORP().ref(defaultRef);
    ledger(l -> {
        l.unverifiedTransaction(tx -> {
            tx.output("alice's $900",
                    new Cash.State(issuedBy(DOLLARS(900), issuer), getALICE_PUBKEY(), null));
            return Unit.INSTANCE;
        });

        // Some CP is issued onto the ledger by MegaCorp.
        l.transaction("Issuance", tx -> {
            tx.output("paper", getPaper());
            tx.command(getMEGA_CORP_PUBKEY(), new JavaCommercialPaper.Commands.Issue());
            tx.timestamp(getTEST_TX_TIME());
            return tx.verifies();
        });

        l.transaction("Trade", tx -> {
            tx.input("paper");
            tx.input("alice's $900");
            tx.output("borrowed $900", new Cash.State(issuedBy(DOLLARS(900), issuer), getMEGA_CORP_PUBKEY(), null));
            JavaCommercialPaper.State inputPaper = l.retrieveOutput(JavaCommercialPaper.State.class, "paper");
            tx.output("alice's paper", inputPaper.withOwner(getALICE_PUBKEY()));
            tx.command(getALICE_PUBKEY(), new Cash.Commands.Move());
            tx.command(getMEGA_CORP_PUBKEY(), new JavaCommercialPaper.Commands.Move());
            return tx.verifies();
        });

        l.tweak(lw -> {
            lw.transaction(tx -> {
                tx.input("paper");
                JavaCommercialPaper.State inputPaper = l.retrieveOutput(JavaCommercialPaper.State.class, "paper");
                // We moved a paper to another pubkey.
                tx.output("bob's paper", inputPaper.withOwner(getBOB_PUBKEY()));
                tx.command(getMEGA_CORP_PUBKEY(), new JavaCommercialPaper.Commands.Move());
                return tx.verifies();
            });
            lw.fails();
            return Unit.INSTANCE;
        });
        l.verifies();
        return Unit.INSTANCE;
    });
}