# 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:

```bash
# 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):

```bash
# 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