Automated Testing Workflow

This page documents the GitHub Actions workflow defined in `.github/workflows/test.yml`() that runs the project's automated test suite. It covers trigger conditions, the runner environment, dependency installation, and how the PERPLEXITY_API_KEY stub is supplied so tests can execute without a real API credential.

For information about the test configuration, coverage settings, and the npm test script itself, see 8.2 Building and Testing. For the other CI/CD workflows that publish packages and validate plugins, see 9.2 NPM Publishing Workflow, 9.3 MCP Registry Publishing Workflow, and 9.4 Plugin Validation Workflow.

---

Triggers

The workflow runs on two event types:

Event	Condition
pull_request	Any PR targeting any branch
push	Commits pushed directly to the main branch

There is no path filter — every pull request and every push to main triggers the test job, regardless of which files changed. This is intentional: any change to the repository should be validated before it lands.

Sources: `.github/workflows/test.yml3-7()

---

Workflow Steps

Workflow step diagram

Sources: `.github/workflows/test.yml1-27()

Step 1 — Checkout

Uses actions/checkout@v6 to clone the repository into the runner's workspace. No additional options are set; it checks out the default branch or the PR's head commit.

Step 2 — Node.js Setup

Uses actions/setup-node@v6 with node-version: '20'. Node 20 is the LTS version targeted by the project. No npm cache configuration is declared in the workflow; npm ci handles reproducibility through the lockfile.

Step 3 — Install Dependencies

Runs npm ci, which installs exact dependency versions from package-lock.json and fails fast if the lockfile is out of date with package.json. This ensures the CI environment is identical to a clean local install.

Step 4 — Run Tests

Runs npm test with the environment variable PERPLEXITY_API_KEY set to the literal string test-api-key.

env:
 PERPLEXITY_API_KEY: test-api-key

This stub value satisfies the API key presence check in src/index.ts and src/server.ts without making real network calls. The same stub is also set in vitest.config.ts for local test runs, ensuring behavior is consistent between CI and local development.

Sources: `.github/workflows/test.yml24-27(), `vitest.config.ts6-8()

---

The PERPLEXITY_API_KEY Stub

The test suite requires PERPLEXITY_API_KEY to be present because createPerplexityServer() in src/server.ts reads it at initialization time. Tests mock or stub network calls rather than hitting the real Perplexity API, so the value of the key does not matter — only its presence does.

This stub is declared in two places to keep CI and local environments consistent:

Location	Declaration
.github/workflows/test.yml	env.PERPLEXITY_API_KEY: test-api-key (step-level)
vitest.config.ts	test.env.PERPLEXITY_API_KEY: 'test-api-key'

API key stub flow

Sources: `.github/workflows/test.yml24-27(), `vitest.config.ts6-8()

---

Vitest Configuration Summary

The npm test command invokes vitest, which reads `vitest.config.ts`(). The relevant settings:

Setting	Value	Effect
test.exclude	**/node_modules/**, **/dist/**	Skips compiled output and installed packages
test.env.PERPLEXITY_API_KEY	'test-api-key'	Provides stub key for local runs
coverage.provider	'v8'	Uses Node's built-in V8 coverage engine
coverage.reporter	['text', 'html', 'lcov']	Outputs to terminal, HTML, and lcov formats
coverage.exclude	node_modules, dist, *.test.ts, *.config.ts	Excludes non-source files from coverage metrics

Coverage is not collected during the standard npm test run in CI — it requires a separate npm run test:coverage invocation. The workflow defined in test.yml only runs npm test, which runs the test suite without generating coverage artifacts.

Sources: `vitest.config.ts1-20()

---

Relationship to Other Workflows

test.yml is the only workflow with no path filter. All other publish and validation workflows are path-scoped. This means the test job acts as a blanket correctness gate for every change, while publication steps are selectively triggered by changes to their relevant configuration files.

Sources: `.github/workflows/test.yml3-7()