name: test-smart-contracts
description: Testing patterns for Algorand smart contracts using generated clients and algorandFixture. Use when writing tests for smart contracts, setting up test fixtures and deployment, debugging failing tests, testing multi-user scenarios, or asking about E2E vs unit testing. Strong triggers include "how do I test my contract", "algorandFixture", "test is failing", "LocalNet testing", "vitest setup", "fund contract for boxes".

Testing Smart Contracts

Write integration tests for Algorand smart contracts using the algorandFixture and generated typed clients.

Default: Integration Tests (E2E)

Always write integration tests unless the user explicitly requests unit tests. Integration tests run against LocalNet and test real contract behavior.

Test Framework: Both Vitest (default) and Jest are supported. The examples below use Vitest syntax, but Jest equivalents work identically.

File naming

• Integration tests: contract.algo.e2e.spec.ts
• Unit tests (only if requested): contract.algo.spec.ts

Canonical Example

Study and adapt from: devportal-code-examples/contracts/HelloWorld

import { Config } from '@algorandfoundation/algokit-utils'
import { algorandFixture } from '@algorandfoundation/algokit-utils/testing'
import { Address } from 'algosdk'
import { beforeAll, beforeEach, describe, expect, test } from 'vitest'
import { MyContractFactory } from '../artifacts/clients/MyContract/MyContractClient'

describe('MyContract', () => {
  const localnet = algorandFixture()

  beforeAll(() => {
    Config.configure({ debug: true })
  })
  // 10-second timeout: LocalNet needs time to process transactions and confirm blocks
  beforeEach(localnet.newScope, 10_000)

  const deploy = async (account: Address) => {
    const factory = localnet.algorand.client.getTypedAppFactory(MyContractFactory, {
      defaultSender: account,
    })
    const { appClient } = await factory.deploy({
      onUpdate: 'append',
      onSchemaBreak: 'append',
      suppressLog: true,
    })
    return { client: appClient }
  }

  test('should call method and verify result', async () => {
    const { testAccount } = localnet.context
    const { client } = await deploy(testAccount)

    const result = await client.send.myMethod({ args: { value: 42n } })
    expect(result.return).toBe(42n)
  })
})

How to proceed

1. Locate the generated client in artifacts/clients/<ContractName>/<ContractName>Client.ts
2. Import the Factory (e.g., MyContractFactory) - NOT the Client directly
3. Use the deploy helper pattern shown above
4. Call methods via client.send.methodName() or client.newGroup().methodName().send()

Critical Rules

Common Patterns

Fund contract for box storage

await localnet.algorand.send.payment({
  amount: (1).algo(),
  sender: testAccount,
  receiver: client.appAddress,
})

Multiple users on same contract

// Create and fund second user
const user2 = localnet.algorand.account.random()
await localnet.algorand.send.payment({
  amount: (5).algo(),
  sender: testAccount,
  receiver: user2.addr,
})

// Get client for same app with different sender
const client2 = factory.getAppClientById({
  appId: client.appId,
  defaultSender: user2.addr,
})

Box references

import { ABIUintType } from 'algosdk'

function createBoxReference(appId: bigint, prefix: string, key: bigint) {
  const uint64Type = new ABIUintType(64)
  const encodedKey = uint64Type.encode(key)
  const boxName = new Uint8Array([...new TextEncoder().encode(prefix), ...encodedKey])
  return { appId, name: boxName }
}

await client.send.setBoxMap({
  args: { key: 1n, value: 'hello' },
  boxReferences: [createBoxReference(client.appId, 'boxMap', 1n)],
})

References

• Canonical Examples - Complete patterns from algorandfoundation repos
• Unit Testing Guide - Only use if user requests unit tests
• devportal-code-examples