# Writing a contract test

This tutorial will take you through the steps required to write a contract test using Kotlin and/or 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:

    @Test
    fun emptyLedger() {
        ledger {
        }
    }

    import static com.r3corda.core.testing.JavaTestHelpers.*;
    import static com.r3corda.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.

Let’s add a Cash transaction:

    @Test
    fun simpleCashDoesntCompile() {
        val inState = Cash.State(
                amount = 1000.DOLLARS `issued by` DUMMY_CASH_ISSUER,
                owner = DUMMY_PUBKEY_1
        )
        ledger {
            transaction {
                input(inState)
            }
        }
    }

    @Test
    public void simpleCashDoesntCompile() {
        Cash.State inState = new Cash.State(
                issuedBy(DOLLARS(1000), getDUMMY_CASH_ISSUER()),
                getDUMMY_PUBKEY_1()
        );
        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:(26, 21) Kotlin: Type mismatch: inferred type is Unit but EnforceVerifyOrFail was expected

    Error:(26, 31) 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 simpleCash() {
        val inState = Cash.State(
                amount = 1000.DOLLARS `issued by` MEGA_CORP.ref(1, 1),
                owner = DUMMY_PUBKEY_1
        )
        ledger {
            transaction {
                input(inState)
                this.verifies()
            }
        }
    }

    @Test
    public void simpleCash() {
        Cash.State inState = new Cash.State(
                issuedBy(DOLLARS(1000), getMEGA_CORP().ref((byte)1, (byte)1)),
                getDUMMY_PUBKEY_1()
        );
        ledger(l -> {
            l.transaction(tx -> {
                tx.input(inState);
                return tx.verifies();
            });
            return Unit.INSTANCE;
        });
    }

The code finally compiles. When run, it produces the following error:

    com.r3corda.core.contracts.TransactionVerificationException$ContractRejection: java.lang.IllegalArgumentException: Failed requirement: for deposit [01] at issuer Snake Oil Issuer the amounts balance

Note

The reference here to the ‘Snake Oil Issuer’ is because we are using the pre-canned `DUMMY_CASH_ISSUER` identity as the issuer of our cash.

The transaction verification failed, because the sum of inputs does not equal the sum of outputs. We can specify that this is intended behaviour by changing `this.verifies()` to `this `fails with` "the amounts balance"`:

    @Test
    fun simpleCashFailsWith() {
        val inState = Cash.State(
                amount = 1000.DOLLARS `issued by` MEGA_CORP.ref(1, 1),
                owner = DUMMY_PUBKEY_1
        )
        ledger {
            transaction {
                input(inState)
                this `fails with` "the amounts balance"
            }
        }
    }

    @Test
    public void simpleCashFailsWith() {
        Cash.State inState = new Cash.State(
                issuedBy(DOLLARS(1000), getMEGA_CORP().ref((byte)1, (byte)1)),
                getDUMMY_PUBKEY_1()
        );
        ledger(l -> {
            l.transaction(tx -> {
                tx.input(inState);
                return tx.failsWith("the amounts balance");
            });
            return Unit.INSTANCE;
        });
    }

We can continue to build the transaction until it `verifies`:

    @Test
    fun simpleCashSuccess() {
        val inState = Cash.State(
                amount = 1000.DOLLARS `issued by` MEGA_CORP.ref(1, 1),
                owner = DUMMY_PUBKEY_1
        )
        ledger {
            transaction {
                input(inState)
                this `fails with` "the amounts balance"
                output(inState.copy(owner = DUMMY_PUBKEY_2))
                command(DUMMY_PUBKEY_1) { Cash.Commands.Move() }
                this.verifies()
            }
        }
    }

    @Test
    public void simpleCashSuccess() {
        Cash.State inState = new Cash.State(
                issuedBy(DOLLARS(1000), getMEGA_CORP().ref((byte)1, (byte)1)),
                getDUMMY_PUBKEY_1()
        );
        ledger(l -> {
            l.transaction(tx -> {
                tx.input(inState);
                tx.failsWith("the amounts balance");
                tx.output(inState.copy(inState.getAmount(), getDUMMY_PUBKEY_2()));
                tx.command(getDUMMY_PUBKEY_1(), new Cash.Commands.Move());
                return tx.verifies();
            });
            return Unit.INSTANCE;
        });
    }

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

We constructed a complete signed cash transaction from `DUMMY_PUBKEY_1` to `DUMMY_PUBKEY_2` 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 ruin the transaction for good... Enter `tweak`:

    @Test
    fun simpleCashTweakSuccess() {
        val inState = Cash.State(
                amount = 1000.DOLLARS `issued by` MEGA_CORP.ref(1, 1),
                owner = DUMMY_PUBKEY_1
        )
        ledger {
            transaction {
                input(inState)
                this `fails with` "the amounts balance"
                output(inState.copy(owner = DUMMY_PUBKEY_2))

                tweak {
                    command(DUMMY_PUBKEY_2) { Cash.Commands.Move() }
                    this `fails with` "the owning keys are the same as the signing keys"
                }

                command(DUMMY_PUBKEY_1) { Cash.Commands.Move() }
                this.verifies()
            }
        }
    }

    @Test
    public void simpleCashTweakSuccess() {
        Cash.State inState = new Cash.State(
                issuedBy(DOLLARS(1000), getMEGA_CORP().ref((byte)1, (byte)1)),
                getDUMMY_PUBKEY_1()
        );
        ledger(l -> {
            l.transaction(tx -> {
                tx.input(inState);
                tx.failsWith("the amounts balance");
                tx.output(inState.copy(inState.getAmount(), getDUMMY_PUBKEY_2()));

                tx.tweak(tw -> {
                    tw.command(getDUMMY_PUBKEY_2(), new Cash.Commands.Move());
                    return tw.failsWith("the owning keys are the same as the signing keys");
                });
                tx.command(getDUMMY_PUBKEY_1(), new Cash.Commands.Move());
                return tx.verifies();
            });
            return Unit.INSTANCE;
        });
    }

`tweak` creates a local copy of the transaction. This allows the local “ruining” of the transaction 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 toplevel `transaction` primitive that creates a ledger with a single transaction:

    @Test
    fun simpleCashTweakSuccessTopLevelTransaction() {
        val inState = Cash.State(
                amount = 1000.DOLLARS `issued by` MEGA_CORP.ref(1, 1),
                owner = DUMMY_PUBKEY_1
        )
        transaction {
            input(inState)
            this `fails with` "the amounts balance"
            output(inState.copy(owner = DUMMY_PUBKEY_2))

            tweak {
                command(DUMMY_PUBKEY_2) { Cash.Commands.Move() }
                this `fails with` "the owning keys are the same as the signing keys"
            }

            command(DUMMY_PUBKEY_1) { Cash.Commands.Move() }
            this.verifies()
        }
    }

    @Test
    public void simpleCashTweakSuccessTopLevelTransaction() {
        Cash.State inState = new Cash.State(
                issuedBy(DOLLARS(1000), getMEGA_CORP().ref((byte)1, (byte)1)),
                getDUMMY_PUBKEY_1()
        );
        transaction(tx -> {
            tx.input(inState);
            tx.failsWith("the amounts balance");
            tx.output(inState.copy(inState.getAmount(), getDUMMY_PUBKEY_2()));

            tx.tweak(tw -> {
                tw.command(getDUMMY_PUBKEY_2(), new Cash.Commands.Move());
                return tw.failsWith("the owning keys are the same as the signing keys");
            });
            tx.command(getDUMMY_PUBKEY_1(), new Cash.Commands.Move());
            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 chainCash() {
        ledger {
            unverifiedTransaction {
                output("MEGA_CORP cash") {
                    Cash.State(
                            amount = 1000.DOLLARS `issued by` MEGA_CORP.ref(1, 1),
                            owner = MEGA_CORP_PUBKEY
                    )
                }
            }

            transaction {
                input("MEGA_CORP cash")
                output("MEGA_CORP cash".output<Cash.State>().copy(owner = DUMMY_PUBKEY_1))
                command(MEGA_CORP_PUBKEY) { Cash.Commands.Move() }
                this.verifies()
            }
        }
    }

    @Test
    public void chainCash() {
        ledger(l -> {
            l.unverifiedTransaction(tx -> {
                tx.output("MEGA_CORP cash",
                        new Cash.State(
                                issuedBy(DOLLARS(1000), getMEGA_CORP().ref((byte)1, (byte)1)),
                                getMEGA_CORP_PUBKEY()
                        )
                );
                return Unit.INSTANCE;
            });

            l.transaction(tx -> {
                tx.input("MEGA_CORP cash");
                Cash.State inputCash = l.retrieveOutput(Cash.State.class, "MEGA_CORP cash");
                tx.output(inputCash.copy(inputCash.getAmount(), getDUMMY_PUBKEY_1()));
                tx.command(getMEGA_CORP_PUBKEY(), new Cash.Commands.Move());
                return tx.verifies();
            });

            return Unit.INSTANCE;
        });
    }

In this example we declare that `MEGA_CORP` has a thousand dollars but we don’t care where from, for this we can use `unverifiedTransaction`. Note how we don’t need to specify `this.verifies()`.

The `output` cash was labelled with `"MEGA_CORP cash"`, we can subsequently referred to this other transactions, e.g. by `input("MEGA_CORP cash")` or `"MEGA_CORP cash".output<Cash.State>()`.

What happens if we reuse the output cash twice?

    @Test
    fun chainCashDoubleSpend() {
        ledger {
            unverifiedTransaction {
                output("MEGA_CORP cash") {
                    Cash.State(
                            amount = 1000.DOLLARS `issued by` MEGA_CORP.ref(1, 1),
                            owner = MEGA_CORP_PUBKEY
                    )
                }
            }

            transaction {
                input("MEGA_CORP cash")
                output("MEGA_CORP cash".output<Cash.State>().copy(owner = DUMMY_PUBKEY_1))
                command(MEGA_CORP_PUBKEY) { Cash.Commands.Move() }
                this.verifies()
            }

            transaction {
                input("MEGA_CORP cash")
                // We send it to another pubkey so that the transaction is not identical to the previous one
                output("MEGA_CORP cash".output<Cash.State>().copy(owner = DUMMY_PUBKEY_2))
                command(MEGA_CORP_PUBKEY) { Cash.Commands.Move() }
                this.verifies()
            }
        }
    }

    @Test
    public void chainCashDoubleSpend() {
        ledger(l -> {
            l.unverifiedTransaction(tx -> {
                tx.output("MEGA_CORP cash",
                        new Cash.State(
                                issuedBy(DOLLARS(1000), getMEGA_CORP().ref((byte)1, (byte)1)),
                                getMEGA_CORP_PUBKEY()
                        )
                );
                return Unit.INSTANCE;
            });

            l.transaction(tx -> {
                tx.input("MEGA_CORP cash");
                Cash.State inputCash = l.retrieveOutput(Cash.State.class, "MEGA_CORP cash");
                tx.output(inputCash.copy(inputCash.getAmount(), getDUMMY_PUBKEY_1()));
                tx.command(getMEGA_CORP_PUBKEY(), new Cash.Commands.Move());
                return tx.verifies();
            });

            l.transaction(tx -> {
                tx.input("MEGA_CORP cash");
                Cash.State inputCash = l.retrieveOutput(Cash.State.class, "MEGA_CORP cash");
                // We send it to another pubkey so that the transaction is not identical to the previous one
                tx.output(inputCash.copy(inputCash.getAmount(), getDUMMY_PUBKEY_2()));
                tx.command(getMEGA_CORP_PUBKEY(), new Cash.Commands.Move());
                return tx.verifies();
            });

            return Unit.INSTANCE;
        });
    }

The transactions `verifies()` individually, however the state was spent twice!

We can also verify the complete ledger by calling `verifies`/`fails` on the ledger level. We can also use `tweak` to create a local copy of the whole ledger:

    @Test
    fun chainCashDoubleSpendFailsWith() {
        ledger {
            unverifiedTransaction {
                output("MEGA_CORP cash") {
                    Cash.State(
                            amount = 1000.DOLLARS `issued by` MEGA_CORP.ref(1, 1),
                            owner = MEGA_CORP_PUBKEY
                    )
                }
            }

            transaction {
                input("MEGA_CORP cash")
                output("MEGA_CORP cash".output<Cash.State>().copy(owner = DUMMY_PUBKEY_1))
                command(MEGA_CORP_PUBKEY) { Cash.Commands.Move() }
                this.verifies()
            }

            tweak {
                transaction {
                    input("MEGA_CORP cash")
                    // We send it to another pubkey so that the transaction is not identical to the previous one
                    output("MEGA_CORP cash".output<Cash.State>().copy(owner = DUMMY_PUBKEY_1))
                    command(MEGA_CORP_PUBKEY) { Cash.Commands.Move() }
                    this.verifies()
                }
                this.fails()
            }

            this.verifies()
        }
    }

    @Test
    public void chainCashDoubleSpendFailsWith() {
        ledger(l -> {
            l.unverifiedTransaction(tx -> {
                tx.output("MEGA_CORP cash",
                        new Cash.State(
                                issuedBy(DOLLARS(1000), getMEGA_CORP().ref((byte)1, (byte)1)),
                                getMEGA_CORP_PUBKEY()
                        )
                );
                return Unit.INSTANCE;
            });

            l.transaction(tx -> {
                tx.input("MEGA_CORP cash");
                Cash.State inputCash = l.retrieveOutput(Cash.State.class, "MEGA_CORP cash");
                tx.output(inputCash.copy(inputCash.getAmount(), getDUMMY_PUBKEY_1()));
                tx.command(getMEGA_CORP_PUBKEY(), new Cash.Commands.Move());
                return tx.verifies();
            });

            l.tweak(lw -> {
                lw.transaction(tx -> {
                    tx.input("MEGA_CORP cash");
                    Cash.State inputCash = l.retrieveOutput(Cash.State.class, "MEGA_CORP cash");
                    // We send it to another pubkey so that the transaction is not identical to the previous one
                    tx.output(inputCash.copy(inputCash.getAmount(), getDUMMY_PUBKEY_2()));
                    tx.command(getMEGA_CORP_PUBKEY(), new Cash.Commands.Move());
                    return tx.verifies();
                });
                lw.fails();
                return Unit.INSTANCE;
            });

            l.verifies();
            return Unit.INSTANCE;
        });
    }