CIA/e-voting-system/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

```bash
# Install requests library if not already installed
pip install requests
```

## Run Tests

```bash
# 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:
```bash
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:
```bash
# Wait for database initialization
sleep 30

# Run tests again
python3 test_blockchain_election.py
```

If still empty after 30 seconds, check backend logs:
```bash
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
```bash
curl http://localhost:8000/health
```

Expected:
```json
{"status": "ok", "version": "0.1.0"}
```

### Test Blockchain Endpoint
```bash
curl http://localhost:8000/api/elections/blockchain | jq '.'
```

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

### Test Election Verification
```bash
curl http://localhost:8000/api/elections/1/blockchain-verify | jq '.'
```

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

### Test Active Elections
```bash
curl http://localhost:8000/api/elections/active | jq '.'
```

### Test Debug Elections
```bash
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**
   ```bash
   curl http://localhost:8000/api/elections/blockchain
   ```

2. **Verify an election**
   ```bash
   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.