# CDK FFI Python Tests

This directory contains Python tests for the CDK FFI (Foreign Function Interface) bindings, covering both transaction operations and wallet database operations.

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

**No manual file copying required!**

## Test Suite

### Transaction Tests (explicit transaction management)

Tests that use `begin_db_transaction()`, `commit()`, and `rollback()`:

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 in one transaction
6. **Transaction Atomicity** - Tests that rollback properly reverts ALL changes
7. **Get Proofs by Y Values (Transaction)** - Tests retrieving proofs within transactions

### Wallet Tests (direct wallet methods)

Tests that use wallet database methods directly without explicit transactions:

8. **Wallet Creation** - Tests creating a wallet with SQLite backend
9. **Wallet Mint Management** - Tests adding, querying, and removing mints
10. **Wallet Keyset Management** - Tests adding and querying keysets
11. **Wallet Keyset Counter** - Tests keyset counter increment operations
12. **Wallet Quote Operations** - Tests querying mint and melt quotes
13. **Wallet Get Proofs by Y Values** - Tests retrieving proofs by Y values

### Key Features Tested

**Transaction Features:**
- ✅ **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
- ✅ **Explicit rollback** - Manual transaction rollback

**Wallet Features:**
- ✅ **Wallet creation** - SQLite backend initialization
- ✅ **Mint management** - Add, query, and retrieve mint URLs
- ✅ **Keyset operations** - Add keysets and query by ID or mint
- ✅ **Counter operations** - Keyset counter increment/read
- ✅ **Quote queries** - Retrieve mint and melt quotes
- ✅ **Proof retrieval** - Get proofs by Y values
- ✅ **Foreign key constraints** - Proper referential integrity

## Test Output

Expected output for successful run:

```
Starting CDK FFI Wallet and Transaction Tests
==================================================
... (test execution) ...
==================================================
Test Results: 13 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
5. Clearly indicate if the test uses transactions or direct wallet methods

## 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
- Transaction tests demonstrate ACID properties
- Wallet tests demonstrate direct database operations