Testing and Continuous Integration

Code Reviews and Pull Request Acceptance Process

This section outlines the process and rules for submitting and merging Pull Requests (PRs). All code changes must go through this process to ensure quality and stability.

The specifics of this process are specified and enforced using GitHub's Ruleset feature.

General Rules for All Branches

The following rules apply to PRs targeting both the develop and main branches:

• PRs are Mandatory: All commits must be made on a feature branch and submitted via a pull request. Direct pushes to develop and main are blocked.
• Resolve All Conversations: Before a PR can be merged, all comments and requested changes must be addressed and resolved.
• No Force Pushing: Force pushes are disabled on develop and main to protect the commit history.
• Status Checks: In the future, all required status checks (like automated tests and builds) must pass before a PR can be merged.

Branch-Specific Requirements

Merging into develop

The develop branch is our primary integration branch for new features and bugfixes.

• Required Approvals: 1 approving review from another team member is required.

Merging into main

The main branch contains stable, production-ready code. PRs to main typically come from the develop branch.

• Required Approvals: 2 approving reviews from other team members are required.

Version Numbering

Our project will follow the semantic versioning number format.

Tagging Strategy

To track iterations and releases, we use Git tags as follows:

• Tags on develop: We apply tags to the develop branch for each iteration (e.g., v0.1.0, v1.3.0) to mark significant milestones or completion of development cycles. Iterations will bump the minor version number by 1.
• Tags on main: We apply tags to the main branch for official releases (e.g., v1.0.0, v2.1.0) to denote stable versions ready for production. Releases will bump the major version number by 1.

Testing

Our project employs a robust testing strategy across our monorepo, utilizing specific frameworks optimized for each part of the stack (Backend, Frontend, and Automation). We enforce high code quality through unit testing, integration testing, and automated code coverage reporting.

🛠 Tools & Frameworks

Service	Framework	Test Runner	Assertion Library
Backend	Node.js	Vitest	Vitest
Frontend	React Native (Expo)	Jest (jest-expo)	Jest
Automation	n8n	Jest	Jest
Coverage	All	Codecov	N/A

---

📊 Code Coverage Reporting

We use Codecov to aggregate and visualize coverage data.

• Configuration: Defined in codecov.yaml.
• Thresholds: We track coverage metrics separately for backend, frontend, and n8n using Codecov Flags.
• CI Integration: Coverage reports (lcov.info) are automatically uploaded to Codecov via GitHub Actions after every push to main or develop.

🖥 Frontend Testing

The frontend utilizes Jest configured with the jest-expo preset and React Native Testing Library.

What We Test

• Screens & Pages: ensuring main views like Dashboard and ManualClaimPage render critical UI elements.
• Components: Unit tests for reusable UI components (e.g., Buttons, Input fields).
• Navigation: Verifying screen transitions and navigation container setups.

Mocking Strategy

We use Jest's built-in mocking capabilities to isolate components from native modules.

• Native Modules: jest-expo automatically mocks standard Expo modules.
• Styles/Assets: identity-obj-proxy is used to mock CSS and asset imports.
• Libraries: We mock react-native-gesture-handler in our setup file.

Run Frontend Tests:

cd frontend
npm run test        # Run tests
npm run coverage    # Generate coverage report

⚙️ Backend Testing

The backend uses Vitest, a fast unit test framework powered by Vite. It is configured to use the v8 engine for coverage reporting.

What We Test

• Services: Complex business logic (e.g., DelayService, FlightMonitorService, FlightCleanupService).
• Routes: API endpoint testing (e.g., emailRoutes).
• Utilities: Helper functions for dates, logging, and formatting.

Mocking Strategy We rely heavily on Vitest (vi) to mock external dependencies and side effects.

• Database: We mock the Drizzle ORM and Postgres connections (@/db/index.js) to prevent tests from writing to the actual database.
• Environment: We mock process.env to simulate different configurations.
• External APIs: global.fetch and specific service methods are mocked to simulate AirLabs or Email API responses.

Run Backend Tests:

cd backend
npm run test        # Run tests
npm run coverage    # Generate coverage report

⚡ n8n Automation Testing

Our n8n workflows are tested using Jest.

What We Test

• Workflow Triggers: We perform integration-style tests by firing webhooks to local n8n instances.
• Claim Generation: Verifying that payload data sent to the webhook triggers the correct email generation logic.

Run n8n Tests:

cd n8n
npm run test

Continuous Integration Strategy

This project uses GitHub Actions to automate our Continuous Integration pipeline. The goal of our CI setup is to ensure code quality, prevent regressions, and verify build integrity automatically whenever code is contributed.

Overview

Our CI strategy is designed for a monorepo structure. We utilize a "Smart Change Detection" system to only run workflows relevant to the modified files.

Key Features:

• Set up a CI/CD pipeline (GitHub Actions): Automated workflows trigger on specific events.
• Automated Verification: Runs tests and linters automatically on each push or PR.
• Quality Gates: The pipeline is configured to fail builds on test/lint failures, preventing broken code from merging.
• Change Detection: Saves resources by only testing the backend, frontend, or n8n services if files in those directories have changed.

Triggers

The pipelines are triggered on:

• pull_request: Targeted at main or develop branches.
• push: To main or develop branches.
• workflow_dispatch: Manual triggers via the GitHub UI.

Local Pre-Commit Hooks (Husky)

Before code even reaches GitHub, we use Husky to enforce quality standards locally. A pre-commit hook runs lint-staged to ensure that:

1. Frontend: runs linting, formatting checks, and related tests.
2. Backend: runs linting, formatting checks, and related tests.

If these checks fail locally, the commit is aborted.

Workflow Structure

The CI pipelines generally follow a two-stage process:

1. Detect Changes: Checks which directories (backend/, frontend/, n8n/) have been modified.
2. Execute Jobs: Runs the specific CI jobs for the modified components.

Workflow Dependency Visualization:

1. Change Detection

This job checks out the code and identifies modified files. If no changes are detected in a specific module, the subsequent heavy jobs for that module are skipped to save build time.

Detect Changes Job (Backend):

Backend Pipeline

Configuration File: .github/workflows/backend_ci.yaml

The Backend CI runs on our self-hosted runners (arc-runner-set) using Node.js 22.

Workflow Steps:

1. Checkout: Retrives the codebase.
2. Setup Node: Configures Node 22 and caches npm dependencies.
3. Install Dependencies: Runs npm ci for a clean install.
4. Format Check: Verifies code formatting using Prettier (npm run format:check).
5. Lint: Static analysis using ESLint (npm run lint).
6. Unit Test: Runs Vitest with coverage (npm run coverage).
7. Build: Verifies the project compiles using TypeScript (npm run build).
8. Codecov: Uploads coverage reports to Codecov for analysis.

Backend CI:

Frontend Pipeline

Configuration File: .github/workflows/frontend_ci.yaml

The Frontend CI handles React Native/Expo verification and build previews for Web and Android.

Job: frontend_ci (Quality Checks)

• Setup: Node 22 environment.
• Format & Lint: Checks formatting (Prettier) and runs Expo Lint.
• Unit Tests: Runs Jest tests (npm run coverage).
• Coverage: Uploads reports to Codecov.

Job: build_web

• Expo Doctor: Validates the Expo environment.
• Build: Exports the web version of the app (npm run build:web-dev).

Job: build_android

• Setup: Installs Java 17, Android SDK, and EAS CLI.
• Caching: Caches Gradle dependencies to speed up future builds.
• Build: Generates an Android preview build via EAS (npm run build:android-prev).

Job: e2e_tests

• Build: Exports the web version of the app (npm run build:web-dev).
• Playwright Setup: Installs playwright and the browsers it needs for the tests.
• E2E Test: Runs the end-to-end tests on the web server.

Frontend CI:

n8n Pipeline

Configuration File: .github/workflows/n8n_ci.yaml

Currently, the n8n pipeline serves as a placeholder for future automation regarding our workflow automation service.

• Current Status: Checks for file changes in the n8n/ directory.
• Future Roadmap: Will include dependency installation and workflow testing.

n8n CI: