A
Aura Core Research SMART CONTRACT TUTORIALS
Home / Smart Contract Tutorials / aura-core-51-aiken-unit-testing
Cardano Smart Contract Development Series · Part 04 · AURA #51

Aiken 단위 테스트: 정상 통과와 실패 케이스를 검증하는 방법

Cardano 스마트 컨트랙트 언어 Aiken의 내장 테스트 시스템, test 구문, 정상 통과(Happy Path) 테스트, 잘못된 서명자 거부(!), Datum 누락에 따른 예상 실패(fail) 테스트 및 테스트 한계 분석

PK
Paul Ko (Cardano Ambassador & DRep)
Published: 2026-11-07 · Series: Developer Tutorial
#Aiken #Cardano #UnitTest #aiken_check #eUTxO
기술적 범위 및 작성 원칙 안내 본 글은 Aiken의 테스트 프레임워크 문법과 테스트 케이스 설계 방법을 설명하는 교육용 기술 자료입니다. 본 문서의 작성 과정에서 별도의 로컬 컴파일러 실행이나 자동화 테스트 러너 통과가 확인되었다는 의미는 아니며, 예제 코드는 Aiken 공식 문서와 표준 명세를 기반으로 설명합니다.

1 이번 글에서 배울 것

스마트 컨트랙트는 블록체인에 배포된 이후 기존 스크립트 자체를 임의로 교체할 수 없으며, 변경에는 새로운 스크립트 배포와 주소·상태 이전 등의 설계가 필요할 수 있습니다. 따라서 온체인에 트랜잭션을 제출하기 전에 로컬 환경에서 다양한 시나리오를 단위 테스트(Unit Test)로 검증하는 것은 필수적인 개발 과정입니다.

Aiken은 별도의 외부 테스트 러너나 복잡한 프레임워크를 설치할 필요 없이, 언어 자체에 단위 테스트 기능(test 키워드)이 내장되어 있습니다.

이번 글에서는 앞서 AURA #49와 #50에서 살펴본 owner_lock.ak 컨트랙트를 바탕으로 다음 내용을 다룹니다.

  1. Aiken 내장 테스트 시스템과 test 구문의 기본 구조
  2. 정상 서명자가 자산을 인출하는 성공(Happy Path) 테스트 작성법
  3. 서명자가 일치하지 않을 때 소비를 거부(False)하는 실패 테스트 작성법
  4. Datum이 누락되었을 때 스크립트 평가가 중단되는 예상 실패(fail) 테스트 작성법
  5. 단위 테스트 결과의 올바른 해석과 실제 네트워크 제출 전 테스트의 한계

2 Aiken의 내장 테스트 시스템

Aiken에서 테스트는 별도의 디렉터리에 분리하거나, 검증기 소스 파일(.ak) 내부의 하단에 직접 작성할 수 있습니다.

테스트 함수는 다음과 같이 test 키워드로 선언합니다.

test test_name() {
  // 불리언(Boolean) 표현식
  1 + 1 == 2
}

Aiken 테스트 함수의 핵심 규칙은 다음과 같습니다.

  • 함수의 마지막 평가 결과가 True이면 테스트 러너가 통과로 표시합니다.
  • 결과가 False이거나 실행 도중 오류(fail)가 발생하면 테스트 실패로 처리됩니다.
  • 함수 이름 뒤에 fail 키워드를 붙이면, "이 테스트는 실행 중 반드시 실패(Crash)해야 통과한다"는 예상 실패 테스트(expected-failure test)를 선언할 수 있습니다.

3 테스트를 위한 가상 데이터 구성

단위 테스트는 실제 Cardano 노드나 블록체인 네트워크 없이 로컬 메모리 환경에서 실행됩니다. 따라서 트랜잭션 컨텍스트(Transaction), Datum, Redeemer 등을 테스트 코드 안에서 직접 테스트용 데이터(가상 데이터)로 구성해야 합니다.

참고: 아래 코드는 테스트 함수 내부에서 사용할 지역 변수 선언 예시입니다. 독립적인 모듈 최상위 코드가 아닙니다.
use aiken/crypto.{VerificationKeyHash}

// 가상의 28바이트 공개키 해시 정의 (16진수 바이트열 예시)
let owner_hash: VerificationKeyHash =
  #"01020304050607080910111213141516171819202122232425262728"

Aiken의 표준 라이브러리(cardano/transaction)는 테스트 작성을 돕기 위해 기본값이 채워진 빈 트랜잭션 템플릿인 transaction.placeholder를 제공합니다. 이를 활용하면 필요한 필드(예: extra_signatories)만 부분 수정하여 간결하게 테스트용 트랜잭션을 만들 수 있습니다.

또한 OutputReference는 단위 테스트에서 사용하는 가상 참조이며, 실제 온체인 트랜잭션의 유효한 입력 참조라는 뜻은 아닙니다.

4 시나리오 1: 정상 통과(Happy Path) 테스트

첫 번째는 가장 기본적인 정상 동작 검증입니다.

  • 조건: Datum에 올바른 소유자 해시가 들어있고, 트랜잭션의 서명 요구 목록(extra_signatories)에도 동일한 소유자 해시가 포함되어 있는 경우.
  • 기대 결과: owner_lock.spend 핸들러가 True를 반환해야 합니다.
test spend_success() {
  let owner_hash: VerificationKeyHash =
    #"01020304050607080910111213141516171819202122232425262728"

  // 1. 정상 Datum 및 Redeemer 준비
  let datum = Datum { owner: owner_hash }
  let redeemer = Unlock

  // 2. 가상 OutputReference 준비
  let out_ref =
    OutputReference {
      transaction_id: "",
      output_index: 0,
    }

  // 3. 서명자 목록에 소유자 해시를 포함한 트랜잭션 구성
  let tx =
    Transaction {
      ..transaction.placeholder,
      extra_signatories: [owner_hash],
    }

  // 4. Validator 실행 및 결과 검증 (True이어야 통과)
  owner_lock.spend(Some(datum), redeemer, out_ref, tx) == True
}

이 테스트는 owner_lock.spend(...) == True가 최종 평가식이 되므로, 정상적으로 서명 조건이 충족되면 테스트 러너가 통과로 표시합니다.

5 시나리오 2: 잘못된 서명자 거부(False) 테스트

스마트 컨트랙트 검증에서는 "성공해야 할 때 성공하는 것"만큼이나 "거부되어야 할 때 확실히 거부되는 것"을 검증하는 것이 중요합니다.

  • 조건: Datum의 소유자는 A인데, 트랜잭션 서명자 목록에는 전혀 다른 B의 해시(fake_hash)만 포함된 경우.
  • 기대 결과: owner_lock.spend 핸들러가 False를 반환해야 합니다.

이때 테스트 함수 자체는 "거부 동작이 올바르게 일어났음"을 확인하여 성공해야 하므로, 반환값인 False를 부정 연산자(!)로 뒤집거나 == False로 검사합니다.

test spend_wrong_signer_reject() {
  let owner_hash: VerificationKeyHash =
    #"01020304050607080910111213141516171819202122232425262728"
  let fake_hash: VerificationKeyHash =
    #"99999999999999999999999999999999999999999999999999999999"

  let datum = Datum { owner: owner_hash }
  let redeemer = Unlock

  let out_ref =
    OutputReference {
      transaction_id: "",
      output_index: 0,
    }

  // 서명자 목록에 소유자가 아닌 엉뚱한 해시만 등록
  let tx =
    Transaction {
      ..transaction.placeholder,
      extra_signatories: [fake_hash],
    }

  // Validator가 False를 반환하는지 확인
  !owner_lock.spend(Some(datum), redeemer, out_ref, tx)
}

Validator가 소유자 서명이 없음을 감지하여 False를 반환하면, !False는 True가 되어 이 테스트는 통과합니다. 만약 결함으로 인해 True가 반환된다면 테스트는 실패하게 됩니다.

6 시나리오 3: Datum 누락 및 충돌(fail) 테스트

AURA #49와 #50에서 살펴보았듯이, Datum이 아예 전달되지 않으면(None) expect Some(Datum { owner }) = datum 구문에 의해 스크립트 평가 자체가 중단(Evaluation Failure / Crash)됩니다.

이러한 비정상 종료를 단위 테스트로 검증할 때는 함수 선언부 끝에 fail 수정자(Modifier)를 지정합니다.

test spend_missing_datum_crash() fail {
  let owner_hash: VerificationKeyHash =
    #"01020304050607080910111213141516171819202122232425262728"
  let redeemer = Unlock

  let out_ref =
    OutputReference {
      transaction_id: "",
      output_index: 0,
    }

  let tx =
    Transaction {
      ..transaction.placeholder,
      extra_signatories: [owner_hash],
    }

  // datum 인자로 None을 전달하여 강제 충돌 유도
  owner_lock.spend(None, redeemer, out_ref, tx)
}

test ... fail (예상 실패 테스트)의 동작과 보안상 주의점

Aiken 공식 문서에서 test ... fail은 테스트 실행이 실패해야 테스트 자체가 통과하는 예상 실패 테스트(expected-failure test)로 정의됩니다.

일반 테스트는 실행 중 에러가 발생하면 실패로 처리되지만, fail 수정자가 붙은 테스트는 실행 도중 fail 또는 expect 불일치가 발생해야만 테스트 러너가 통과로 표시합니다. 만약 스크립트가 비정상적인 입력(None)을 받고도 에러 없이 무사히 종료된다면, 오히려 테스트 러너는 이를 결함으로 판단하여 테스트를 실패시킵니다.

보안 테스트 주의 사항 예상 실패 테스트가 통과했다고 해서 의도한 실패 원인까지 자동으로 증명되는 것은 아닙니다. 테스트 대상 코드와 입력을 단순하게 유지하고, 실패를 유도한 조건을 분리하여 다른 오류 때문에 테스트가 통과한 것은 아닌지 확인해야 합니다.

7 테스트 결과 해석과 테스트의 한계

Aiken CLI 환경에서 단위 테스트는 일반적으로 aiken check 명령을 통해 실행할 수 있습니다. 공식 문서에 따르면 이 명령은 프로젝트의 모듈을 컴파일하고 내장된 모든 테스트를 수행합니다.

Aiken 테스트는 실제 운영 Validator와 동일한 가상 머신(Plutus VM) 환경에서 실행되고 CPU·메모리 사용량도 함께 추적할 수 있어, 단순한 일반 소프트웨어 테스트보다 온체인 실행 로직에 훨씬 가까운 검증이 가능합니다.

단위 테스트가 대체할 수 없는 원장 수준의 제약

그렇더라도 단위 테스트가 실제 원장의 전체 검증 절차와 오프체인 트랜잭션 조립까지 대신하지는 않습니다. 다음과 같은 현실적인 제약을 이해해야 합니다.

  1. 원장의 전체 트랜잭션 검증 미대체: 단위 테스트는 Validator 함수와 테스트에서 구성한 입력·컨텍스트를 검증하며, 원장의 전체 트랜잭션 검증을 대체하지는 않습니다. 실제 네트워크에서는 프로토콜 파라미터에 따른 트랜잭션 크기 제한, 최소 UTxO 요구량(min-UTxO), 수수료 등 원장 수준의 제약도 충족해야 합니다. 이러한 조건은 로컬 단위 테스트만으로 실제 네트워크 제출 가능성까지 보장하지 않습니다.
  2. 오프체인 조립 불일치: 테스트에서 작성한 가상 트랜잭션 구조와, 오프체인 트랜잭션 빌더(Mesh, Lucid, Cardano CLI 등)가 실제로 직렬화(CBOR)하여 제출하는 트랜잭션 구조 사이에 불일치가 존재할 수 있습니다.

따라서 단위 테스트는 스마트 컨트랙트 로직 검증의 첫 단계로 활용하고, 이후 CIP-0057 Plutus Blueprint 빌드(aiken build), 실행 예산 분석(ExUnits Budgeting), 그리고 Preprod 테스트넷에서의 트랜잭션 전송 테스트가 순차적으로 이어져야 합니다.

8 핵심 요약

테스트 유형 선언 구문 통과 기준 목적
정상 통과 테스트 test name() { ... } 최종 평가식이 True 정상 권한자의 올바른 자산 인출 검증
거부 실패 테스트 test name() { !... } Validator가 False 반환 → 부정식 결과가 True → 테스트 통과 무권한자의 부적격 요청이 거부되는지 검증
예상 실패 테스트 test name() fail { ... } 실행 중 expect 실패 또는 fail 발생 데이터 누락 등 비정상 입력 시 안전한 중단 검증

다음 AURA #52에서는 이렇게 검증된 코드를 실제 블록체인에서 사용할 수 있는 온체인 아티팩트로 컴파일하는 aiken build와 CIP-0057 Plutus Blueprint의 구조를 살펴봅니다.


기술적 범위 및 작성 원칙 안내

본 글은 Aiken의 단위 테스트 프레임워크와 테스트 케이스 설계 원리를 설명하는 교육용 기술 자료입니다. 실제 Aiken 컴파일, 자동화 테스트 실행 또는 테스트넷 배포가 완료되었다는 의미는 아닙니다.

이전 아티클 (AURA #50) Datum, Redeemer와 Transaction Context: Aiken Validator는 무엇을 읽는가?
다음 아티클 (AURA #52) 다음 편 준비 중 (aiken build와 CIP-0057 Plutus Blueprint)