chore: add testing framework and update README for testing instructions

.github/workflows/README.md

@@ -0,0 +1,79 @@
+# GitHub Actions Workflows
+
+This directory contains automated CI/CD workflows for the Currents MCP Server project.
+
+## Available Workflows
+
+### `test.yml` - Unit Tests
+
+Runs the unit test suite on every push and pull request.
+
+**Triggers:**
+
+- Push to any branch
+- Pull requests to any branch
+
+**What it does:**
+
+1. Checks out the code
+2. Sets up Node.js (tests on both Node 20.x and 22.x)
+3. Installs dependencies using `npm ci`
+4. Runs the test suite with `npm run test:run`
+5. Generates code coverage reports
+6. Optionally uploads coverage to Codecov (requires `CODECOV_TOKEN` secret)
+
+**Matrix Strategy:**
+The workflow runs tests on multiple Node.js versions to ensure compatibility:
+
+- Node.js 20.x (LTS)
+- Node.js 22.x (Latest)
+
+**Coverage Reports:**
+Coverage reports are generated for all Node versions, but only uploaded from Node 20.x to avoid duplicate reports. Coverage files are located in `mcp-server/coverage/`.
+
+## Secrets
+
+The following secrets can be configured in your repository settings:
+
+- `CODECOV_TOKEN` (optional): Token for uploading coverage reports to Codecov. If not set, the upload step will be skipped without failing the build.
+
+## Local Testing
+
+To run the same tests locally that run in CI:
+
+```bash
+cd mcp-server
+npm ci
+npm run test:run
+npm run test:coverage
+```
+
+## Troubleshooting
+
+### Tests fail in CI but pass locally
+
+- Ensure you're using the same Node.js version as CI (check the matrix versions)
+- Run `npm ci` instead of `npm install` to ensure exact dependency versions
+- Check for race conditions or timing issues in tests
+
+### Coverage upload fails
+
+- Verify the `CODECOV_TOKEN` secret is set correctly
+- The workflow is configured to not fail if coverage upload fails (`fail_ci_if_error: false`)
+
+### Workflow doesn't trigger
+
+- Ensure the `.github/workflows/` directory is in the root of your repository
+- Check that your branch protection rules aren't preventing the workflow from running
+- Verify the workflow file has proper YAML syntax
+
+## Adding New Workflows
+
+To add a new workflow:
+
+1. Create a new `.yml` file in this directory
+2. Define the workflow name, triggers, and jobs
+3. Test it on a feature branch before merging to main
+4. Document it in this README
+
+For more information on GitHub Actions syntax, see the [official documentation](https://docs.github.com/en/actions).

.github/workflows/test.yml

@@ -0,0 +1,31 @@
+name: Unit Tests
+
+on:
+  push:
+    branches: ["**"]
+  pull_request:
+    branches: ["**"]
+
+jobs:
+  test:
+    name: Run Unit Tests
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js 22.x
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22.x
+          cache: "npm"
+          cache-dependency-path: mcp-server/package-lock.json
+
+      - name: Install dependencies
+        working-directory: ./mcp-server
+        run: npm ci
+
+      - name: Run tests
+        working-directory: ./mcp-server
+        run: npm run test:run

.gitignore

@@ -4,4 +4,5 @@ build
 .currents-debug
 test-results
 playwright-report
-.cursor
+.cursor
+coverage

README.md

@@ -1,5 +1,7 @@
 # Currents MCP Server
 
+![Unit Tests](https://github.com/currents-dev/currents-mcp/actions/workflows/test.yml/badge.svg)
+
 This is a MCP server that allows you to provide test results context to your AI agents by connecting them to Currents. Useful for asking AI to fix or optimize tests failing in CI.
 
 [![Install MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=currents&config=eyJjb21tYW5kIjoibnB4IC15IEBjdXJyZW50cy9tY3AiLCJlbnYiOnsiQ1VSUkVOVFNfQVBJX0tFWSI6InlvdXItYXBpLWtleSJ9fQ%3D%3D)
@@ -94,7 +96,12 @@ We welcome contributions of all kinds—bug fixes, features, and documentation u
    ```bash
    npm run build
    ```
-4. Run locally (stdio):
+4. Run tests:
+   ```bash
+   npm test
+   ```
+   See [TESTING.md](./mcp-server/TESTING.md) for more details on testing.
+5. Run locally (stdio):
    ```bash
    npm start
    ```
@@ -125,18 +132,19 @@ Example snippet for a client config:
 ```
 
 ### Test tools locally
+
 To test the tools locally without any LLM, you can use the following command:
+
 ```bash
  npm run build
 ```
 
 then run the tools script:
+
 ```bash
  node scripts/call-tools.js
 ```
 
-
-
 ### Making Changes
 
 - Create a feature branch:
@@ -147,6 +155,11 @@ then run the tools script:
   ```bash
   npm run build && npm start
   ```
+- Write tests for your changes in `*.test.ts` files alongside your code
+- Run tests to ensure everything works:
+  ```bash
+  npm test
+  ```
 - Keep changes focused and documented (add comments/types where helpful).
 
 ### Commit and PR Guidelines

mcp-server/TESTING.md

@@ -0,0 +1,89 @@
+# Testing Guide
+
+This project uses [Vitest](https://vitest.dev/) for unit testing.
+
+## Running Tests
+
+### Run tests in watch mode (default)
+
+```bash
+npm test
+```
+
+### Run tests once (CI mode)
+
+```bash
+npm run test:run
+```
+
+### Run tests with UI
+
+```bash
+npm run test:ui
+```
+
+### Run tests with coverage
+
+```bash
+npm run test:coverage
+```
+
+## Writing Tests
+
+Test files should be placed alongside the source files they test, using the naming convention:
+
+- `*.test.ts` for TypeScript tests
+- `*.spec.ts` for specification tests
+
+### Example Test Structure
+
+```typescript
+import { describe, it, expect, vi, beforeEach } from "vitest";
+
+describe("MyModule", () => {
+  beforeEach(() => {
+    // Setup before each test
+  });
+
+  it("should do something", () => {
+    // Test implementation
+    expect(true).toBe(true);
+  });
+});
+```
+
+## Mocking
+
+Vitest provides powerful mocking capabilities:
+
+### Mocking modules
+
+```typescript
+vi.mock("./module.js", () => ({
+  someFunction: vi.fn(),
+}));
+```
+
+### Mocking fetch
+
+```typescript
+global.fetch = vi.fn().mockResolvedValue({
+  ok: true,
+  json: async () => ({ data: "test" }),
+});
+```
+
+## Configuration
+
+The test configuration is in `vitest.config.ts`. Key settings:
+
+- **Environment**: Node.js
+- **Globals**: Enabled (no need to import `describe`, `it`, `expect`)
+- **Coverage Provider**: v8
+- **Test Pattern**: `**/*.{test,spec}.{ts,tsx}`
+
+## Coverage
+
+Coverage reports are generated in the `coverage/` directory when running `npm run test:coverage`.
+
+Coverage thresholds and exclusions can be configured in `vitest.config.ts`.