Merge pull request #197 from williamsokperez-arch/integration

feat: built a comprehensive integration testing suite for the FuTuRe backend

Author: Mystery-CLI

.github/workflows/integration-tests.yml

@@ -0,0 +1,62 @@
+name: Integration Tests
+
+on:
+  push:
+    branches: [ main, master ]
+  pull_request:
+    branches: [ main, master ]
+
+jobs:
+  integration-test:
+    runs-on: ubuntu-latest
+
+    services:
+      postgres:
+        image: postgres:16-alpine
+        env:
+          POSTGRES_DB: future_test
+          POSTGRES_USER: future_admin
+          POSTGRES_PASSWORD: test_password
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd pg_isready
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Use Node.js
+      uses: actions/setup-node@v4
+      with:
+        node-version: '20'
+        cache: 'npm'
+
+    - name: Install dependencies
+      run: npm install
+
+    - name: Run Prisma Migrations
+      run: npx prisma migrate deploy
+      working-directory: ./backend
+      env:
+        DATABASE_URL: postgresql://future_admin:test_password@localhost:5432/future_test
+
+    - name: Run Integration Tests
+      run: npm run test:integration:all
+      working-directory: ./backend
+      env:
+        DATABASE_URL: postgresql://future_admin:test_password@localhost:5432/future_test
+        NODE_ENV: test
+        JWT_SECRET: test-secret
+        STELLAR_NETWORK: testnet
+        HORIZON_URL: https://horizon-testnet.stellar.org
+
+    - name: Upload Test Reports
+      uses: actions/upload-artifact@v4
+      if: always()
+      with:
+        name: integration-test-reports
+        path: backend/test-reports/
+        retention-days: 30

TESTING.md

@@ -28,12 +28,39 @@ To run tests in watch mode (best for development):
 npx vitest
 ```
 
-To run tests in watch mode:
+## 3. Integration Testing Suite
+
+We maintain a comprehensive integration testing suite that covers multiple layers:
+
+- **Service Integration**: Tests internal service logic and interactions (e.g., `TransactionService` + `Cache` + `EventStore`).
+- **Third-party Integration**: Verifies interactions with external APIs like CoinGecko and Stellar Horizon.
+- **API Integration**: End-to-end testing of REST endpoints, including authentication and validation.
+- **Database Integration**: Real Prisma/Postgres testing for data persistence and schema integrity.
+
+### Running Integration Tests
+
+To run all integration tests:
 ```bash
-npx vitest
+cd backend
+npm run test:integration:all
+```
+
+### Environment Setup
+
+Database integration tests require a running Postgres instance. You can start one using Docker:
+```bash
+docker-compose -f docker-compose.test.yml up -d
 ```
+Then, ensure your `DATABASE_URL` environment variable points to the test database:
+`postgresql://future_admin:test_password@localhost:5433/future_test`
+
+### Automated Testing (CI)
+
+Integration tests are automatically run on every Pull Request to `main` or `master` via GitHub Actions. The CI environment handles the database setup and migration automatically.
+
+---
 
-## 3. Testing Best Practices
+## 4. Testing Best Practices
 
 - **AAA Pattern**: Follow the **Arrange, Act, Assert** structure for all tests.
 - **Isolation**: Each test should be independent. Do not rely on the state from a previous test.

backend/package.json

@@ -11,6 +11,8 @@
     "load-test:endpoints": "k6 run load-tests/k6/scenarios/api-endpoints.js",
     "load-test:concurrent": "k6 run load-tests/k6/scenarios/concurrent-users.js",
     "test:integration": "vitest run tests/stellar.integration.test.js",
+    "test:db": "vitest run tests/database.framework.test.js",
+    "test:integration:all": "vitest run tests/*.integration.test.js"
     "test:db": "vitest run tests/database.framework.test.js"
   },
   "dependencies": {

backend/src/services/stellar.js

@@ -106,7 +106,6 @@ export async function sendPayment(sourceSecret, destination, amount, assetCode =
   let result;
   try {
     result = await getHorizonServer().submitTransaction(transaction);
-    result = await server.submitTransaction(transaction);
   } catch (err) {
     logger.error('stellar.sendPayment.failed', { source: sourcePublicKey, destination, amount, assetCode, error: err.message });
     throw err;
@@ -242,15 +241,15 @@ export async function getTransactions(publicKey, { cursor, limit = 10, type, dat
 }
 
 export async function getFeeStats() {
-  const stats = await server.feeStats();
+  const stats = await getHorizonServer().feeStats();
   const feeStroops = parseInt(stats.fee_charged?.p50 ?? StellarSDK.BASE_FEE);
   const feeXLM = feeStroops / 1e7;
 
   // Fetch XLM/USD price via Stellar SDEX (XLM/USDC order book)
   let xlmUsd = null;
   try {
     const usdc = new StellarSDK.Asset('USDC', 'GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN');
-    const book = await server.orderbook(StellarSDK.Asset.native(), usdc).limit(1).call();
+    const book = await getHorizonServer().orderbook(StellarSDK.Asset.native(), usdc).limit(1).call();
     const ask = parseFloat(book.asks?.[0]?.price);
     if (ask > 0) xlmUsd = ask;
   } catch (_) {}
@@ -290,7 +289,7 @@ export async function getExchangeRate(from, to) {
   try {
     const fromAsset = from === 'XLM' ? StellarSDK.Asset.native() : new StellarSDK.Asset(from, getIssuer(from));
     const toAsset   = to   === 'XLM' ? StellarSDK.Asset.native() : new StellarSDK.Asset(to,   getIssuer(to));
-    const orderbook = await server.orderbook(fromAsset, toAsset).call();
+    const orderbook = await getHorizonServer().orderbook(fromAsset, toAsset).call();
     const bestAsk = orderbook.asks?.[0]?.price;
     return bestAsk ? parseFloat(bestAsk) : null;
   } catch (err) {

backend/tests/api.integration.test.js

@@ -0,0 +1,64 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import request from 'supertest';
+import app from './helpers/full-app.js';
+
+describe('API Integration: Auth + User Flows', () => {
+  const testUser = {
+    username: 'testuser' + Math.floor(Math.random() * 10000),
+    password: 'Password123!',
+  };
+
+  let accessToken = '';
+
+  it('should register a new user', async () => {
+    const res = await request(app)
+      .post('/api/auth/register')
+      .send(testUser);
+
+    expect(res.status).toBe(201);
+    expect(res.body.user).toHaveProperty('id');
+    expect(res.body.user.username).toBe(testUser.username);
+  });
+
+  it('should login and return access/refresh tokens', async () => {
+    const res = await request(app)
+      .post('/api/auth/login')
+      .send(testUser);
+
+    expect(res.status).toBe(200);
+    expect(res.body).toHaveProperty('accessToken');
+    expect(res.body).toHaveProperty('refreshToken');
+    accessToken = res.body.accessToken;
+  });
+
+  it('should access protected profile with a valid token', async () => {
+    const res = await request(app)
+      .get('/api/auth/profile')
+      .set('Authorization', `Bearer ${accessToken}`);
+
+    expect(res.status).toBe(200);
+    expect(res.body.username).toBe(testUser.username);
+  });
+
+  it('should return 401 for accessing profile without token', async () => {
+    const res = await request(app).get('/api/auth/profile');
+    expect(res.status).toBe(401);
+  });
+
+  it('should return 422 for invalid registration data', async () => {
+    const res = await request(app)
+      .post('/api/auth/register')
+      .send({ username: 'tu', password: '1' }); // too short
+
+    expect(res.status).toBe(422);
+    expect(res.body.errors).toBeInstanceOf(Array);
+  });
+});
+
+describe('API Integration: Health & Network', () => {
+  it('should return health status', async () => {
+    const res = await request(app).get('/health');
+    expect(res.status).toBe(200);
+    expect(res.body.status).toBe('ok');
+  });
+});

backend/tests/database.integration.test.js

@@ -0,0 +1,81 @@
+import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+import prisma, { connectDB, disconnectDB } from '../src/db/client.js';
+
+// Skip if no DATABASE_URL is set
+const hasDb = !!process.env.DATABASE_URL;
+
+describe.runIf(hasDb)('Database Integration: Prisma + Postgres', () => {
+  beforeAll(async () => {
+    await connectDB();
+    // In a real integration test, we might run migrations here or use a shadow DB
+  });
+
+  afterAll(async () => {
+    await disconnectDB();
+  });
+
+  it('should create and retrieve a user', async () => {
+    const publicKey = 'G' + Math.random().toString(36).substring(2, 12).toUpperCase();
+    
+    const user = await prisma.user.create({
+      data: { publicKey }
+    });
+
+    expect(user).toHaveProperty('id');
+    expect(user.publicKey).toBe(publicKey);
+
+    const retrieved = await prisma.user.findUnique({
+      where: { id: user.id }
+    });
+    expect(retrieved.publicKey).toBe(publicKey);
+  });
+
+  it('should manage user settings with cascade delete', async () => {
+    const user = await prisma.user.create({
+      data: { 
+        publicKey: 'G' + Math.random().toString(36).substring(2, 12).toUpperCase(),
+        settings: {
+          create: { defaultAsset: 'USDC' }
+        }
+      },
+      include: { settings: true }
+    });
+
+    expect(user.settings.defaultAsset).toBe('USDC');
+
+    // Delete user and verify settings are gone
+    await prisma.user.delete({ where: { id: user.id } });
+    
+    const settings = await prisma.setting.findUnique({
+      where: { userId: user.id }
+    });
+    expect(settings).toBeNull();
+  });
+
+  it('should record a transaction between two users', async () => {
+    const sender = await prisma.user.create({ data: { publicKey: 'GSENDER' + Math.random().toString(36).substring(2, 12).toUpperCase() } });
+    const recipient = await prisma.user.create({ data: { publicKey: 'GRECIPIENT' + Math.random().toString(36).substring(2, 12).toUpperCase() } });
+    
+    const txHash = 'hash' + Math.random().toString(36).substring(2, 12);
+
+    const tx = await prisma.transaction.create({
+      data: {
+        hash: txHash,
+        amount: 100.50,
+        senderId: sender.id,
+        recipientId: recipient.id,
+        successful: true
+      }
+    });
+
+    expect(tx.senderId).toBe(sender.id);
+    expect(tx.recipientId).toBe(recipient.id);
+    expect(tx.amount.toString()).toBe('100.5');
+  });
+});
+
+if (!hasDb) {
+  describe('Database Integration: Prisma + Postgres', () => {
+    it.skip('Skipped: DATABASE_URL not set', () => {});
+  });
+}

backend/tests/helpers/full-app.js

@@ -0,0 +1,30 @@
+import express from 'express';
+import cors from 'cors';
+import stellarRoutes from '../../src/routes/stellar.js';
+import authRoutes from '../../src/routes/auth.js';
+import transactionRoutes from '../../src/routes/transactions.js';
+
+// Setup environment for testing
+process.env.NODE_ENV = 'test';
+process.env.JWT_SECRET = 'test-secret';
+process.env.STELLAR_NETWORK = 'testnet';
+process.env.HORIZON_URL = 'https://horizon-testnet.stellar.org';
+
+const app = express();
+app.use(cors());
+app.use(express.json());
+
+// Mount routes
+app.use('/api/stellar', stellarRoutes);
+app.use('/api/auth', authRoutes);
+app.use('/api/transactions', transactionRoutes);
+
+// Health check
+app.get('/health', (_req, res) => res.json({ status: 'ok', network: 'testnet' }));
+
+// Global error handler for tests
+app.use((err, req, res, next) => {
+  res.status(err.status || 500).json({ error: err.message });
+});
+
+export default app;

backend/tests/helpers/integration-reporter.js

@@ -0,0 +1,63 @@
+import { fileURLToPath } from 'url';
+import { dirname, resolve } from 'path';
+import fs from 'fs';
+
+export default class IntegrationReporter {
+  constructor() {
+    this.results = [];
+    this.startTime = Date.now();
+  }
+
+  onTestFinished(test) {
+    this.results.push({
+      name: test.name,
+      fullName: test.result?.state === 'fail' ? test.suite?.name + ' > ' + test.name : test.name,
+      status: test.result?.state,
+      duration: test.result?.duration,
+      error: test.result?.errors?.[0]?.message
+    });
+  }
+
+  onFinished(files) {
+    const duration = (Date.now() - this.startTime) / 1000;
+    const passed = this.results.filter(r => r.status === 'pass').length;
+    const failed = this.results.filter(r => r.status === 'fail').length;
+    const skipped = this.results.filter(r => r.status === 'skip').length;
+
+    const summary = {
+      timestamp: new Date().toISOString(),
+      durationSeconds: duration,
+      total: this.results.length,
+      passed,
+      failed,
+      skipped,
+      details: this.results
+    };
+
+    const __dirname = dirname(fileURLToPath(import.meta.url));
+    const reportDir = resolve(__dirname, '../../test-reports');
+    
+    if (!fs.existsSync(reportDir)) {
+      fs.mkdirSync(reportDir, { recursive: true });
+    }
+
+    fs.writeFileSync(
+      resolve(reportDir, 'integration-report.json'),
+      JSON.stringify(summary, null, 2)
+    );
+
+    console.log('\n\x1b[36mIntegration Test Summary:\x1b[39m');
+    console.log(`\x1b[32mPassed:  ${passed}\x1b[39m`);
+    console.log(`\x1b[31mFailed:  ${failed}\x1b[39m`);
+    console.log(`\x1b[34mSkipped: ${skipped}\x1b[39m`);
+    console.log(`Duration: ${duration.toFixed(2)}s\n`);
+    
+    if (failed > 0) {
+      console.log('\x1b[31mFailures:\x1b[39m');
+      this.results.filter(r => r.status === 'fail').forEach(r => {
+        console.log(`  - ${r.fullName}: \x1b[31m${r.error}\x1b[39m`);
+      });
+      console.log('\n');
+    }
+  }
+}