cdk/crates/cdk-ffi/tests/README.md

CDK FFI Python Tests

This directory contains Python tests for the CDK FFI (Foreign Function Interface) bindings.

Running the Tests

Quick Start

The easiest way to run all tests:

# From the repository root
just ffi-test

This command will automatically:

1. Build the FFI bindings (if needed)
2. Run all Python tests
3. Report results

Or run directly (assumes bindings are already built):

# From the repository root
python3 crates/cdk-ffi/tests/test_transactions.py

Prerequisites

Python 3.7+ is required. The just ffi-test command handles everything else automatically.

How It Works

The test script automatically:

1. Locates the bindings in target/bindings/python/
2. Copies the shared library from target/release/ to the bindings directory
3. Runs all transaction tests

No manual file copying required!

Test Suite

Transaction Tests (test_transactions.py)

Comprehensive tests for database transaction operations:

1. Increment Counter with Commit - Tests increment_keyset_counter() and persistence
2. Implicit Rollback on Drop - Verifies automatic rollback when transactions are dropped
   
3. Explicit Rollback - Tests manual rollback() calls
4. Transaction Reads - Tests reading data within active transactions
5. Multiple Increments - Tests sequential counter operations
6. Wallet Mint Operations - Tests adding and removing mints in transactions
7. Wallet Proof Operations - Basic proof database operations
8. Wallet Quote Operations - Basic quote operations
   
9. Wallet Balance Query - Basic balance query operations
10. Wallet Transaction Atomicity - Tests that rollback properly reverts ALL changes

Key Features Tested

• ✅ Transaction atomicity - All-or-nothing commits/rollbacks
• ✅ Isolation - Uncommitted changes not visible outside transaction
• ✅ Durability - Committed changes persist
• ✅ Implicit rollback - Automatic cleanup on transaction drop
• ✅ Counter operations - Keyset counter increment/read
• ✅ Mint management - Add/remove mints with proper constraints
• ✅ Foreign key constraints - Proper referential integrity

Test Output

Expected output for successful run:

Starting CDK FFI Transaction Tests
==================================================
... (test execution) ...
==================================================
Test Results: 10 passed, 0 failed
==================================================

Troubleshooting

Import Errors

If you see ModuleNotFoundError: No module named 'cdk_ffi':

• Ensure FFI bindings are generated: just ffi-generate python
• Check that target/bindings/python/cdk_ffi.py exists

Library Not Found

If you see errors about missing .dylib or .so files:

• Build the release version: cargo build --release -p cdk-ffi
• Check that the library exists in target/release/

Test Failures

If tests fail:

• Ensure you're running from the repository root
• Check that the FFI bindings match the current code version
• Try rebuilding: just ffi-generate python && cargo build --release -p cdk-ffi

Development

When adding new tests:

1. Add test function with async def test_*() signature
2. Add test to the tests list in main()
3. Use temporary databases for isolation
4. Follow existing patterns for setup/teardown

Implementation Notes

• All tests use temporary SQLite databases
• Each test is fully isolated with its own database
• Tests clean up automatically via finally blocks
• The script handles path resolution and library loading automatically