Testing

Test Clarity smart contracts and Next.js frontends with stacksdapp test — Vitest simnet tests in contracts/tests/ without Docker.

stacksdapp test runs contract tests (Clarinet SDK with vitest-environment-clarinet) and frontend tests (Vitest). No Docker or local devnet is required for contract tests.

Contents

• Run all tests
• Contract tests
• ABI caching
• Type-check before testing
• Frontend tests
• Tips

Run all tests

stacksdapp test

This runs:

• Contracts: Vitest + Clarinet SDK in contracts/tests/ (global simnet from vitest-environment-clarinet)
• Frontend: Vitest in frontend/ (vitest run --passWithNoTests)

Contract tests

Tests live under contracts/tests/. The scaffold template uses the clarinet Vitest environment with a global simnet instance:

import { describe, expect, it } from "vitest";
import { Cl } from "@stacks/transactions";

const accounts = simnet.getAccounts();
const deployer = accounts.get("deployer")!;

describe("counter", () => {
  it("increments", () => {
    const { result } = simnet.callPublicFn("counter", "increment", [], deployer);
    expect(result).toBeOk(Cl.uint(1));
  });
  it("decrement", () => {
    simnet.callPublicFn("counter", "increment", [], deployer);
    const { result } = simnet.callPublicFn("counter", "decrement", [], deployer);
    expect(result).toBeOk(Cl.uint(0));
  });
});

SIP template tests are generated automatically when you run stacksdapp add --template sip010|sip009.

Requires Clarinet 3.23+ and matching @stacks/clarinet-sdk in the contracts package.

ABI caching

Contract ABIs are cached under contracts/.cache/. Unchanged sources skip redundant initSimnet runs during generate and test workflows.

Type-check before testing

stacksdapp check

Validates Clarity syntax and types without deployment.

Frontend tests

Frontend Vitest suites live under frontend/. They run as part of stacksdapp test even if you have not written tests yet.

Tips

• Use simnet tests for contract logic
• Use local devnet or testnet for full wallet flows
• After editing contracts, run stacksdapp generate so bindings stay aligned with tests that import generated code
• Prefer testnet over devnet for reliable deploy verification