Contract Test

Scalus Smart Contract Testing

Before writing test code from memory, fetch https://scalus.org/llms-api.txt and check the testkit signatures you plan to use.

Documentation

In the Scalus repo, read scalus-site/content/<path>.mdx; in any other project, fetch https://scalus.org/docs/<path>.md.

Testing fundamentals:

• testing/unit-testing - ScalusTest trait, property-based testing
• smart-contracts/evaluating-script - Script evaluation patterns
• testing/debugging - Debugging techniques

Integration testing:

• testing/emulator - in-memory Emulator testing
• testing/local-devnet - Yaci DevKit integration tests
• Use the local-development skill for the full Emulator + TxBuilder loop.

Test Examples

Study existing tests before writing new ones:

• Fetch https://scalus.org/llms-examples.txt - validators with their tests; HtlcTest.scala is the reference style.
• In the Scalus repo: scalus-examples/jvm/src/test/scala/scalus/examples/.

Testing Patterns

Emulator test with ScalusTest (the standard pattern; see HtlcTest):

class MyValidatorTest extends AnyFunSuite, ScalusTest {
    private given env: CardanoInfo = TestUtil.testEnvironment
    private val contract = MyContract.compiled.withErrorTraces

    test("valid spend succeeds") {
        val provider = Emulator.withAddresses(Seq(Alice.address, Bob.address))
        val utxos = provider.findUtxos(address = Alice.address).await().toOption.get
        // build a transaction with txBuilder, then:
        assert(provider.submit(tx).await().isRight)
    }
}

Assertions from scalus.testing.kit:

• assertScriptFail(expectedError) { buildTx } - expect a validator failure
• assertEvalResult(expected)(program) - check an evaluation result

Budget assertions from scalus.testing.dsl.EvalTestDsl:

• .assertBudgetWithin(memory, steps) - upper bound
• .assertBudgetEquals(memory, steps) - exact pin (baseline tests)

Pin convention:

• Every new prelude/stdlib operation gets a budget: test in scalus-core that pins mem, cpu and the mainnet fee: assertEvalWithBudgetAndFee(code, arg, expected, ExUnits(memory = m, steps = s), Coin(fee)) from scalus.testing.kit.EvalTestKit. Pass the input as arg (it goes in as Data) so constant folding cannot remove the work being measured.
• Example validator tests pin the exact ExUnits of every transaction, and the fee where the test already does (result.budget.fee == Coin(2398) in HtlcTest). Wrap a pin in ScalaCompilerVersion.baseline(pre38 = ..., since38 = ...) only when the two compiler generations differ; otherwise write the bare value.
• Format: ExUnits(memory = 27127, steps = 11_541882), named parameters, _ at the million boundary.

Property-based testing: ScalusTest provides generators (e.g. genByteStringOfN); use ScalaCheck forAll for on-chain function properties.

Negative cases: three idioms; pick one per test, do not mix them:

• Builder path (HtlcTest): keep the default evaluator and wrap the build in assertScriptFail(expectedError) { buildTx }. The builder runs the script while balancing, throws, and the helper matches expectedError against the script logs, so pass the validator's own error constant.
• Emulator path (EditableNftValidatorTest): build with TxBuilder(env, PlutusScriptEvaluator.constMaxBudget(env)) so the builder skips script evaluation, then provider.submit(tx).await() and assert(result.isLeft). Use it when the transaction must get past the builder (for example, to reach the ledger's own checks).
• Unit path (VestingValidatorTest): build a ScriptContext by hand, run compiled.runScript(ctx) and assert(result.isFailure, "..."). For an on-chain helper evaluated directly, assertEvalFailsWithMessage[OnchainError](msg)(expr) checks the message.