Merge pull request #589 from itsjaneossai/Stellar

Stellar

Author: LaGodxy

.github/workflows/contract-tests.yml

@@ -0,0 +1,158 @@
+name: Contract Tests
+
+on:
+  push:
+    branches: [main, develop]
+    paths:
+      - 'src/**'
+      - 'test/contracts/**'
+      - '.github/workflows/contract-tests.yml'
+  pull_request:
+    branches: [main]
+  repository_dispatch:
+    types: [pact-changed]
+
+env:
+  NODE_VERSION: '20'
+  PACT_BROKER_URL: ${{ secrets.PACT_BROKER_URL }}
+  PACT_BROKER_TOKEN: ${{ secrets.PACT_BROKER_TOKEN }}
+
+jobs:
+  consumer-contracts:
+    name: Consumer Contract Tests
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: ${{ env.NODE_VERSION }}
+          cache: 'npm'
+      - run: npm ci
+      - name: Run consumer contract tests
+        run: npm run test:consumer
+        env:
+          CONSUMER_VERSION: ${{ github.sha }}
+          GIT_BRANCH: ${{ github.head_ref || github.ref_name }}
+      - name: Upload pact files
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: pact-files
+          path: pact/contracts/
+          retention-days: 30
+      - name: Publish pacts to Pact Broker
+        if: github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name == github.repository
+        run: npm run pact:publish
+        env:
+          CONSUMER_VERSION: ${{ github.sha }}
+          GIT_BRANCH: ${{ github.head_ref || github.ref_name }}
+      - name: Can I Deploy? (Consumer)
+        if: github.event_name != 'pull_request'
+        run: |
+          npx pact-broker can-i-deploy \
+            --pacticipant ApiGateway \
+            --version ${{ github.sha }} \
+            --to-environment production \
+            --broker-base-url ${{ env.PACT_BROKER_URL }} \
+            --broker-token ${{ env.PACT_BROKER_TOKEN }}
+
+  provider-verification:
+    name: Provider Verification
+    runs-on: ubuntu-latest
+    needs: consumer-contracts
+    if: always() && (needs.consumer-contracts.result == 'success' || github.event_name == 'repository_dispatch')
+    services:
+      user-service:
+        image: strellerminds/user-service:latest
+        ports:
+          - 3001:3001
+        env:
+          NODE_ENV: test
+        options: >-
+          --health-cmd "curl -f http://localhost:3001/health || exit 1"
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+      auth-service:
+        image: strellerminds/auth-service:latest
+        ports:
+          - 3002:3002
+        env:
+          NODE_ENV: test
+        options: >-
+          --health-cmd "curl -f http://localhost:3002/health || exit 1"
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+      postgres:
+        image: postgres:15
+        env:
+          POSTGRES_USER: test
+          POSTGRES_PASSWORD: test
+          POSTGRES_DB: testdb
+        options: >-
+          --health-cmd pg_isready
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: ${{ env.NODE_VERSION }}
+          cache: 'npm'
+      - run: npm ci
+      - run: sleep 10
+      - name: Verify UserService
+        run: npm run test:provider -- --testPathPattern=user-service
+        env:
+          CI: true
+          USER_SERVICE_URL: http://localhost:3001
+          PROVIDER_VERSION: ${{ github.sha }}
+          GIT_BRANCH: ${{ github.head_ref || github.ref_name }}
+      - name: Verify AuthService
+        run: npm run test:provider -- --testPathPattern=auth-service
+        env:
+          CI: true
+          AUTH_SERVICE_URL: http://localhost:3002
+          PROVIDER_VERSION: ${{ github.sha }}
+          GIT_BRANCH: ${{ github.head_ref || github.ref_name }}
+      - name: Can I Deploy? (Provider)
+        if: github.event_name != 'pull_request'
+        run: |
+          npx pact-broker can-i-deploy \
+            --pacticipant UserService \
+            --version ${{ github.sha }} \
+            --to-environment production \
+            --broker-base-url ${{ env.PACT_BROKER_URL }} \
+            --broker-token ${{ env.PACT_BROKER_TOKEN }}
+
+  generate-docs:
+    name: Generate Contract Documentation
+    runs-on: ubuntu-latest
+    needs: [consumer-contracts, provider-verification]
+    if: github.ref == 'refs/heads/main' && success()
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: ${{ env.NODE_VERSION }}
+          cache: 'npm'
+      - run: npm ci
+      - uses: actions/download-artifact@v4
+        with:
+          name: pact-files
+          path: pact/contracts/
+      - run: npm run docs:generate
+      - uses: actions/upload-artifact@v4
+        with:
+          name: contract-docs
+          path: docs/contracts/
+          retention-days: 90
+      - name: Deploy docs to GitHub Pages
+        if: github.ref == 'refs/heads/main'
+        uses: peaceiris/actions-gh-pages@v3
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./docs/contracts
+          destination_dir: contract-docs

CONTRACTS.md

@@ -0,0 +1,22 @@
+#Contract Testing for StrellerMinds Smart Contracts
+
+##Issue #471 - Status: In Progress
+
+Goal: Add contract testing between microservices and Soroban smart contracts.
+
+### Current Approach (Phone-Friendly Start)
+- Use *Consumer-Driven Contracts* where possible.
+- Start with OpenAPI/Swagger schema validation for REST endpoints.
+- Plan to migrate to **Pact** for full behavioral testing.
+
+### Key Contracts to Cover
+- Soroban contract invocation endpoints
+- User authentication & progress APIs
+- Transaction submission
+
+### Basic Validation Setup
+Add to `package.json` (if Node.js parts exist) or CI:
+```json
+"scripts": {
+  "test:contract": "echo 'Contract tests will run here - using Pact or Spectral for OpenAPI'"
+}

jest.contract.config.js

@@ -0,0 +1,21 @@
+module.exports = {
+  displayName: 'contract-tests',
+  preset: 'ts-jest',
+  testEnvironment: 'node',
+  rootDir: '.',
+  testMatch: [
+    '**/test/contracts/**/*.spec.ts',
+    '**/test/contracts/**/*.test.ts',
+  ],
+  moduleNameMapper: {
+    '@shared/(.*)': '<rootDir>/src/shared/$1',
+  },
+  globals: {
+    'ts-jest': {
+      tsconfig: './tsconfig.json',
+    },
+  },
+  testTimeout: 30000,
+  maxWorkers: 1,
+  verbose: true,
+};

package.json

@@ -3,6 +3,11 @@
     "visual:test": "playwright test --config=visual-tests/playwright.config.ts",
     "visual:test:update": "playwright test --config=visual-tests/playwright.config.ts --update-snapshots",
     "visual:test:report": "playwright show-report visual-tests/playwright-report",
+    "test:contracts": "jest --config jest.contract.config.js",
+    "test:consumer": "jest --config jest.contract.config.js --testPathPattern=consumer",
+    "test:provider": "jest --config jest.contract.config.js --testPathPattern=provider",
+    "pact:publish": "ts-node src/scripts/publish-pacts.ts",
+    "docs:generate": "ts-node src/scripts/generate-docs.ts",
     "a11y:test": "playwright test --config=visual-tests/accessibility.config.ts",
     "a11y:report": "playwright show-report visual-tests/accessibility-report"
   },
@@ -13,6 +18,12 @@
     "@types/node": "^24.6.2",
     "axe-core": "^4.11.3",
     "axios": "^1.12.2",
-    "dotenv": "^17.2.3"
+    "dotenv": "^17.2.3",
+    "@pact-foundation/pact": "^12.0.0",
+    "@pact-foundation/pact-node": "^10.17.7",
+    "jest": "^29.5.0",
+    "ts-jest": "^29.1.0",
+    "ts-node": "^10.9.0",
+    "typescript": "^5.0.0"
+  }
   }
-}

pact/contracts/.gitkeep

@@ -0,0 +1 @@
+

pact/logs/.gitkeep

@@ -0,0 +1 @@
+

src/providers/pact-provider-states.controller.ts

@@ -0,0 +1,56 @@
+import { Controller, Post, Body, HttpCode } from '@nestjs/common';
+
+interface ProviderStateRequest {
+  state: string;
+  action: 'setup' | 'teardown';
+  params?: Record<string, unknown>;
+}
+
+@Controller('_pact')
+export class PactProviderStatesController {
+  private readonly stateHandlers: Record
+    string,
+    { setup: () => Promise<void>; teardown?: () => Promise<void> }
+  > = {
+    'a user with id user-abc-123 exists': {
+      setup: async () => {
+        // TODO: await userRepo.save({ id: 'user-abc-123', ... })
+      },
+      teardown: async () => {
+        // TODO: await userRepo.delete('user-abc-123')
+      },
+    },
+    'a user with id nonexistent does not exist': {
+      setup: async () => {
+        // TODO: ensure user doesn't exist
+      },
+    },
+    'users exist in the system': {
+      setup: async () => {
+        // TODO: seed test users
+      },
+    },
+    'the user system is ready to accept new users': {
+      setup: async () => {
+        // TODO: clear conflicting data
+      },
+    },
+  };
+
+  @Post('provider-states')
+  @HttpCode(200)
+  async handleProviderState(@Body() body: ProviderStateRequest) {
+    const { state, action } = body;
+    const handler = this.stateHandlers[state];
+
+    if (!handler) {
+      console.warn(`[Pact] No handler for state: "${state}"`);
+      return { state, result: 'no-op' };
+    }
+
+    if (action === 'setup') await handler.setup();
+    else if (action === 'teardown' && handler.teardown) await handler.teardown();
+
+    return { state, result: 'ok' };
+  }
+}

src/scripts/generate-docs.ts

@@ -0,0 +1,60 @@
+import * as fs from 'fs';
+import * as path from 'path';
+
+const PACT_DIR = path.resolve(process.cwd(), 'pact/contracts');
+const DOCS_DIR = path.resolve(process.cwd(), 'docs/contracts');
+
+interface PactFile {
+  consumer: { name: string };
+  provider: { name: string };
+  interactions: Array<{
+    description: string;
+    providerState?: string;
+    request: { method: string; path: string; headers?: Record<string,string>; body?: unknown };
+    response: { status: number; headers?: Record<string,string>; body?: unknown };
+  }>;
+  metadata: { pactSpecification: { version: string } };
+}
+
+function generateDoc(pact: PactFile, filename: string): string {
+  let doc = `# Contract: ${pact.consumer.name} → ${pact.provider.name}\n\n`;
+  doc += `> Auto-generated from \`${filename}\`\n\n`;
+  doc += `| Property | Value |\n|---|---|\n`;
+  doc += `| Consumer | ${pact.consumer.name} |\n`;
+  doc += `| Provider | ${pact.provider.name} |\n`;
+  doc += `| Interactions | ${pact.interactions.length} |\n\n`;
+  doc += `## Interactions\n\n`;
+
+  pact.interactions.forEach((i) => {
+    doc += `### ${i.description}\n\n`;
+    if (i.providerState) doc += `> **State:** ${i.providerState}\n\n`;
+    doc += `**Request:** \`${i.request.method} ${i.request.path}\`\n\n`;
+    doc += `**Response:** \`HTTP ${i.response.status}\`\n\n`;
+    if (i.response.body) doc += `\`\`\`json\n${JSON.stringify(i.response.body, null, 2)}\n\`\`\`\n\n`;
+    doc += `---\n\n`;
+  });
+
+  return doc;
+}
+
+async function generateDocs(): Promise<void> {
+  fs.mkdirSync(DOCS_DIR, { recursive: true });
+
+  if (!fs.existsSync(PACT_DIR)) {
+    console.warn('No pact directory found. Run consumer tests first.');
+    return;
+  }
+
+  const files = fs.readdirSync(PACT_DIR).filter((f) => f.endsWith('.json'));
+
+  files.forEach((file) => {
+    const pact: PactFile = JSON.parse(fs.readFileSync(path.join(PACT_DIR, file), 'utf-8'));
+    const doc = generateDoc(pact, file);
+    fs.writeFileSync(path.join(DOCS_DIR, file.replace('.json', '.md')), doc);
+    console.log(`✅ ${file.replace('.json', '.md')}`);
+  });
+
+  console.log(`\nDocs generated in ${DOCS_DIR}`);
+}
+
+generateDocs().catch(console.error);

src/scripts/publish-pacts.ts

@@ -0,0 +1,25 @@
+import { Publisher } from '@pact-foundation/pact-node';
+import { PACT_CONFIG } from '../shared/pact.config';
+
+async function publishPacts(): Promise<void> {
+  const version = process.env.CONSUMER_VERSION || '1.0.0';
+  const branch = process.env.GIT_BRANCH || 'main';
+
+  console.log(`Publishing pacts v${version} (branch: ${branch})...`);
+
+  await new Publisher({
+    pactFilesOrDirs: [PACT_CONFIG.PACT_DIR],
+    pactBroker: PACT_CONFIG.BROKER_URL,
+    pactBrokerToken: PACT_CONFIG.BROKER_TOKEN,
+    consumerVersion: version,
+    branch,
+    tags: [branch, 'latest'],
+  }).publishPacts();
+
+  console.log('✅ Pacts published');
+}
+
+publishPacts().catch((err) => {
+  console.error('Failed to publish pacts:', err);
+  process.exit(1);
+});