CIA/e-voting-system/.claude/RUN_TESTS.md

Running Blockchain Election Tests

Prerequisites

1. Backend is running on http://localhost:8000
2. Wait 30 seconds after backend starts for database initialization
3. Python 3.8+ with requests library installed

Installation

# Install requests library if not already installed
pip install requests

Run Tests

# From project root directory
python3 test_blockchain_election.py

Expected Output

Successful Test Run

╔════════════════════════════════════════════════════════════╗
║                                                            ║
║  Elections Blockchain Integration Tests                   ║
║                                                            ║
╚════════════════════════════════════════════════════════════╝

============================================================
TEST 0: Backend Health Check
============================================================
✓ Backend is running
  Status: ok
  Version: 0.1.0

============================================================
TEST 1: Get Elections Blockchain
============================================================
✓ Blockchain endpoint working
  Total blocks: 1
  Chain valid: true

First block:
  Election ID: 1
  Election name: Election Présidentielle 2025
  Candidates: 4
  Block hash: 7f3e9c2b1d4f8a5c3e1b9d2f...
  Signature: 8a2e1f3d5c9b7a4e6c1d3f5a...

============================================================
TEST 2: Verify Election 1 Blockchain Integrity
============================================================
✓ Verification endpoint working
  Verified: true
  Hash valid: true
  Chain valid: true
  Signature valid: true

✓ Election blockchain integrity VERIFIED

============================================================
TEST 3: Get Active Elections
============================================================
✓ Active elections endpoint working
  Active elections: 1

  Election 1: Election Présidentielle 2025
    Start: 2025-11-07T01:59:00
    End: 2025-11-14T01:59:00
    Active: true

============================================================
TEST 4: Debug All Elections
============================================================
✓ Debug endpoint working
  Current server time: 2025-11-07T03:00:00.123456
  Total elections: 1
  Elections that should be active: 1

Active elections:
  ✓ Election 1: Election Présidentielle 2025

============================================================
TEST SUMMARY
============================================================
✓ PASS: Backend Health
✓ PASS: Blockchain Endpoint
✓ PASS: Active Elections
✓ PASS: Debug Elections
✓ PASS: Election Verification

Total: 5/5 tests passed

✓ All tests passed! Elections blockchain integration working correctly.

Troubleshooting

Error: Cannot connect to backend

✗ Cannot connect to backend
  Is it running on http://localhost:8000?

Solution: Start backend with Docker:

docker compose up -d backend
# Wait 30 seconds for initialization
sleep 30
# Then run tests
python3 test_blockchain_election.py

Error: No blocks in blockchain

✗ Blockchain endpoint working
  Total blocks: 0

⚠ No blocks in blockchain yet
  Elections may not have been initialized

Solution: This is expected if the backend just started. Wait for initialization:

# Wait for database initialization
sleep 30

# Run tests again
python3 test_blockchain_election.py

If still empty after 30 seconds, check backend logs:

docker compose logs backend | grep -i blockchain

Should see:

✓ Recorded election 1 (Election Présidentielle 2025) to blockchain
✓ Blockchain integrity verified - 1 blocks

Error: Verification failed

⚠ Election blockchain verification FAILED
  - Block hash mismatch (possible tampering)

This indicates possible data corruption. Check:

1. Is backend stable (no crashes)?
2. Are there any database errors?
3. Try restarting: docker compose restart backend

Error: Module not found

ModuleNotFoundError: No module named 'blockchain_elections'

This means the backend isn't loading the blockchain module. Check:

1. File exists: backend/blockchain_elections.py
2. Permissions are correct
3. Backend rebuilt after adding module: docker compose up -d --build backend

Manual Testing Commands

Instead of running the full test suite, you can test individual endpoints:

Test Backend Health

curl http://localhost:8000/health

Expected:

{"status": "ok", "version": "0.1.0"}

Test Blockchain Endpoint

curl http://localhost:8000/api/elections/blockchain | jq '.'

Expected:

{
  "blocks": [...],
  "verification": {
    "chain_valid": true,
    "total_blocks": 1
  }
}

Test Election Verification

curl http://localhost:8000/api/elections/1/blockchain-verify | jq '.'

Expected:

{
  "verified": true,
  "election_id": 1,
  "election_name": "...",
  "hash_valid": true,
  "chain_valid": true,
  "signature_valid": true
}

Test Active Elections

curl http://localhost:8000/api/elections/active | jq '.'

Test Debug Elections

curl http://localhost:8000/api/elections/debug/all | jq '.elections'

Interpreting Results

✓ Verified

Election blockchain integrity is valid. Election has not been tampered with.

✗ hash_valid: false

The block's data has been modified after creation. Tampering detected.

✗ chain_valid: false

A previous block in the chain has been modified, breaking the hash chain.

✗ signature_valid: false

The block's signature is missing, invalid, or doesn't match. Authentication failed.

Next Steps

After confirming tests pass:

1. View blockchain via API

   curl http://localhost:8000/api/elections/blockchain
   

2. Verify an election

   curl http://localhost:8000/api/elections/1/blockchain-verify
   

3. Integrate with Frontend (optional)

   • Use frontend/components/blockchain-visualizer.tsx
   • Create a page to display blockchain data
   • Show verification status and block details

4. Extend Blockchain (future)

   • Add voter registration records
   • Record votes to blockchain
   • Implement voting proofs

Test Script Source

The test script (test_blockchain_election.py) is ~290 lines and performs:

1. Health Check - Verifies backend is running
2. Blockchain Endpoint - Tests /api/elections/blockchain
3. Active Elections - Tests /api/elections/active
4. Debug Elections - Tests /api/elections/debug/all
5. Election Verification - Tests /api/elections/{id}/blockchain-verify

Each test:

• Makes HTTP request to backend
• Validates response structure
• Checks for expected fields
• Reports status (✓ PASS or ✗ FAIL)
• Provides debug information on failure

See the script for detailed implementation and test logic.