feat(tests): setup test suite and add basic tests

Author: scottmckendry

.github/workflows/ci.yml

@@ -2,12 +2,30 @@ on:
   push:
     branches:
       - main
+  pull_request:
+    branches:
+      - "*"
 
-name: release-please
+name: ci
 jobs:
+  test:
+    name: Test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+      - name: Install dependencies
+        run: npm ci
+      - name: Run tests
+        run: npm test
+
   release-please:
     name: Release
     runs-on: ubuntu-latest
+    needs: test
     outputs:
       release_created: ${{ steps.release.outputs.release_created }}
       tag_name: ${{ steps.release.outputs.tag_name }}

jest.config.js

@@ -0,0 +1,7 @@
+module.exports = {
+    preset: 'ts-jest',
+    testEnvironment: 'node',
+    testMatch: ['**/tests/**/*.test.ts'],
+    moduleFileExtensions: ['ts', 'js', 'json'],
+    verbose: true,
+};

package-lock.json

@@ -10,7 +10,14 @@
         "dotenv": "^17.0.0"
     },
     "devDependencies": {
-        "@types/node": "^22.15.29"
+        "@types/jest": "^30.0.0",
+        "@types/node": "^22.15.29",
+        "jest": "^30.0.5",
+        "ts-jest": "^29.4.1",
+        "ts-node": "^10.9.2"
+    },
+    "scripts": {
+        "test": "jest"
     },
     "version": "0.5.0"
 }

package.json

@@ -0,0 +1,27 @@
+import { describe, it, expect, beforeEach, jest } from '@jest/globals';
+import { ActualService } from '../src/services/actual-service';
+
+describe('ActualService', () => {
+    const serverURL = 'http://localhost';
+    const password = 'password';
+    const e2eEncryptionPassword = 'e2e';
+    const syncId = 'sync_id';
+    let service: ActualService;
+
+    beforeEach(() => {
+        service = new ActualService(serverURL, password, e2eEncryptionPassword, syncId);
+    });
+
+    it('can be instantiated', () => {
+        expect(service).toBeInstanceOf(ActualService);
+    });
+
+    it('initialize, importTransactions, and shutdown can be called (mocked)', async () => {
+        service.initialize = jest.fn<() => Promise<void>>().mockResolvedValue(undefined);
+        service.importTransactions = jest.fn<(accountId: string, transactions: any[]) => Promise<void>>().mockResolvedValue(undefined);
+        service.shutdown = jest.fn<() => Promise<void>>().mockResolvedValue(undefined);
+        await expect(service.initialize()).resolves.toBeUndefined();
+        await expect(service.importTransactions('acc', [])).resolves.toBeUndefined();
+        await expect(service.shutdown()).resolves.toBeUndefined();
+    });
+});

tests/actual-service.test.ts

@@ -0,0 +1,28 @@
+import { describe, it, expect, beforeEach, jest } from "@jest/globals";
+import { AkahuService } from "../src/services/akahu-service";
+
+describe("AkahuService", () => {
+    const appToken = "app_token";
+    const userToken = "user_token";
+    let service: AkahuService;
+
+    beforeEach(() => {
+        service = new AkahuService(appToken, userToken);
+    });
+
+    it("can be instantiated", () => {
+        expect(service).toBeInstanceOf(AkahuService);
+    });
+
+    it("getTransactions can be called (mocked)", async () => {
+        service.getTransactions = jest
+            .fn<() => Promise<any[]>>()
+            .mockResolvedValue([]);
+        await expect(
+            service.getTransactions({
+                start: "2025-08-01",
+                end: "2025-08-04",
+            } as any),
+        ).resolves.toEqual([]);
+    });
+});

tests/akahu-service.test.ts

@@ -0,0 +1,38 @@
+import { describe, it, expect, beforeEach } from "@jest/globals";
+import { validateEnv } from "../src/utils/env-validator";
+
+describe("validateEnv", () => {
+    beforeEach(() => {
+        process.env.AKAHU_APP_TOKEN = "app_token";
+        process.env.AKAHU_USER_TOKEN = "user_token";
+        process.env.ACTUAL_SERVER_URL = "http://localhost";
+        process.env.ACTUAL_PASSWORD = "password";
+        process.env.ACTUAL_SYNC_ID = "sync_id";
+        process.env.ACCOUNT_MAPPINGS = JSON.stringify({ foo: "bar" });
+        process.env.DAYS_TO_FETCH = "7";
+    });
+
+    it("returns validated config when env is valid", () => {
+        const config = validateEnv();
+        expect(config.akahuAppToken).toBe("app_token");
+        expect(config.accountMappings).toEqual({ foo: "bar" });
+        expect(config.daysToFetch).toBe(7);
+    });
+
+    it("throws if required env var is missing", () => {
+        delete process.env.AKAHU_APP_TOKEN;
+        expect(() => validateEnv()).toThrow(/AKAHU_APP_TOKEN is not set/);
+    });
+
+    it("throws if ACCOUNT_MAPPINGS is empty", () => {
+        process.env.ACCOUNT_MAPPINGS = JSON.stringify({});
+        expect(() => validateEnv()).toThrow(/ACCOUNT_MAPPINGS is empty/);
+    });
+
+    it("throws if DAYS_TO_FETCH is invalid", () => {
+        process.env.DAYS_TO_FETCH = "not_a_number";
+        expect(() => validateEnv()).toThrow(
+            /DAYS_TO_FETCH must be a positive number/,
+        );
+    });
+});

tests/env-validator.test.ts

@@ -0,0 +1,35 @@
+import { describe, it, expect } from "@jest/globals";
+import { transformTransaction } from "../src/utils/transaction-transformer";
+
+describe("transformTransaction", () => {
+    it("transforms an enriched transaction to actual transaction", () => {
+        const enriched = {
+            _id: "tx1",
+            date: "2025-08-01",
+            amount: 12.34,
+            merchant: { name: "Coffee Shop" },
+            description: "Latte",
+            type: "debit",
+            category: { name: "Food" },
+        };
+        const actual = transformTransaction(enriched as any);
+        expect(actual.imported_id).toBe("tx1");
+        expect(actual.date).toEqual(new Date("2025-08-01"));
+        expect(actual.amount).toBe(1234);
+        expect(actual.payee_name).toBe("Coffee Shop");
+        expect(actual.notes).toMatch(/debit/);
+    });
+
+    it("falls back to description if merchant missing", () => {
+        const enriched = {
+            _id: "tx2",
+            date: "2025-08-01",
+            amount: 10,
+            description: "Groceries",
+            type: "debit",
+            category: { name: "Food" },
+        };
+        const actual = transformTransaction(enriched as any);
+        expect(actual.payee_name).toBe("Groceries");
+    });
+});