# What Are the Unit Tests in k-skill? Complete Test Suite Breakdown

> Explore the k-skill unit test suite in the NomaDamas/k-skill repo. Learn how to run tests across 40+ packages using npm test or npm run ci for comprehensive code validation.

- Repository: [NomaDamas/k-skill](https://github.com/NomaDamas/k-skill)
- Tags: deep-dive
- Published: 2026-08-04

---

**The k-skill monorepo contains a comprehensive unit test suite spanning 40+ skill packages, with tests located in `test/` directories under each workspace and runnable via `npm test` or `npm run ci`.**

The **k-skill** repository by NomaDamas is a Node.js-based skill collection for Korean public data APIs. According to the source code, every package ships with dedicated unit tests that validate API normalization, caching behavior, error handling, and security boundaries. This article maps the complete test coverage across the monorepo.

## Core Proxy Server Tests

The `k-skill-proxy` package serves as the central infrastructure layer. Its test suite in `packages/k-skill-proxy/test/` validates request routing, rate limiting, and cache logic shared by all skills.

### Server Fundamentals

The primary test file [`server.test.js`](https://github.com/NomaDamas/k-skill/blob/main/server.test.js) exercises the `buildServer()` factory and `makeCacheKey()` helper:

```js
// packages/k-skill-proxy/test/server.test.js
const test = require('node:test');
const assert = require('node:assert/strict');
const { buildServer } = require('../src/server');

test('makeCacheKey requires a non-empty route to prevent cross-route collisions', () => {
  assert.throws(() => makeCacheKey({ q: '강남' }), /route/);
  const alpha = makeCacheKey({ route: 'alpha', q: 'x' });
  const beta  = makeCacheKey({ route: 'beta',  q: 'x' });
  assert.notEqual(alpha, beta, 'different routes must yield different cache keys');
});

```

This pattern—mock `global.fetch`, inject requests via `app.inject()`, and assert on responses—repeats across all proxy tests.

### Government API Integration Tests

| Service | Test File | Coverage Focus |
|---------|-----------|--------------|
| **Korean National Assembly** | [`assembly-bill-search.test.js`](https://github.com/NomaDamas/k-skill/blob/main/assembly-bill-search.test.js) | Query normalization, API key injection, response caching |
| **KOPIS (Performing Arts)** | [`kopis.test.js`](https://github.com/NomaDamas/k-skill/blob/main/kopis.test.js) | Parameter mapping, semantic error retry logic |
| **KR WHOIS** | [`kr-whois.test.js`](https://github.com/NomaDamas/k-skill/blob/main/kr-whois.test.js) | Domain/IP/AS normalizers, secret key redaction |
| **NHIS (Health Insurance)** | [`nhis.test.js`](https://github.com/NomaDamas/k-skill/blob/main/nhis.test.js) | Long-term care normalizers, retry on semantic failures |
| **NTS Business** | [`nts-business.test.js`](https://github.com/NomaDamas/k-skill/blob/main/nts-business.test.js) | POST body handling, non-caching of sensitive data |
| **Food Safety Korea** | [`food-safety.test.js`](https://github.com/NomaDamas/k-skill/blob/main/food-safety.test.js) | XML/JSON handling, key-validation error recovery |
| **KOSIS (Statistics)** | [`kosis.test.js`](https://github.com/NomaDamas/k-skill/blob/main/kosis.test.js) | Six query normalizers (search, meta, data, list, explain, indicator) |

Additional proxy tests cover [`vworld.test.js`](https://github.com/NomaDamas/k-skill/blob/main/vworld.test.js), [`region-lookup.test.js`](https://github.com/NomaDamas/k-skill/blob/main/region-lookup.test.js), [`naver-shopping.test.js`](https://github.com/NomaDamas/k-skill/blob/main/naver-shopping.test.js), [`naver-news.test.js`](https://github.com/NomaDamas/k-skill/blob/main/naver-news.test.js), [`molit.test.js`](https://github.com/NomaDamas/k-skill/blob/main/molit.test.js), [`lh-notice.test.js`](https://github.com/NomaDamas/k-skill/blob/main/lh-notice.test.js), [`korean-law.test.js`](https://github.com/NomaDamas/k-skill/blob/main/korean-law.test.js), [`hrfco.test.js`](https://github.com/NomaDamas/k-skill/blob/main/hrfco.test.js), [`g2b-order-plan.test.js`](https://github.com/NomaDamas/k-skill/blob/main/g2b-order-plan.test.js), [`ev-charger.test.js`](https://github.com/NomaDamas/k-skill/blob/main/ev-charger.test.js), [`building-register.test.js`](https://github.com/NomaDamas/k-skill/blob/main/building-register.test.js), and [`airkorea.test.js`](https://github.com/NomaDamas/k-skill/blob/main/airkorea.test.js).

## Individual Skill Package Tests

Beyond the proxy, each skill package maintains its own `test/` directory. The monorepo structure uses npm workspaces under `packages/*`.

### Financial & Commercial Skills

- **`toss-securities`** — [`official-client.test.js`](https://github.com/NomaDamas/k-skill/blob/main/official-client.test.js), [`index.test.js`](https://github.com/NomaDamas/k-skill/blob/main/index.test.js) (API client behavior)
- **`daishin-report-search`** — [`index.test.js`](https://github.com/NomaDamas/k-skill/blob/main/index.test.js) (report retrieval)
- **`market-kurly-search`** — [`index.test.js`](https://github.com/NomaDamas/k-skill/blob/main/index.test.js) (e-commerce search)
- **`daiso-product-search`** — [`index.test.js`](https://github.com/NomaDamas/k-skill/blob/main/index.test.js) (product catalog)

### Location & Public Services

- **`public-restroom-nearby`** — [`index.test.js`](https://github.com/NomaDamas/k-skill/blob/main/index.test.js)
- **`parking-lot-search`** — [`index.test.js`](https://github.com/NomaDamas/k-skill/blob/main/index.test.js)
- **`cheap-gas-nearby`** — [`index.test.js`](https://github.com/NomaDamas/k-skill/blob/main/index.test.js)
- **`ev-charger`** — covered in proxy tests; **`ev-subsidy-status`** — [`index.test.js`](https://github.com/NomaDamas/k-skill/blob/main/index.test.js), [`http.test.js`](https://github.com/NomaDamas/k-skill/blob/main/http.test.js), [`browser.test.js`](https://github.com/NomaDamas/k-skill/blob/main/browser.test.js)

### Sports & Entertainment

- **`lck-analytics`** — [`index.test.js`](https://github.com/NomaDamas/k-skill/blob/main/index.test.js) (League of Legends Champions Korea)
- **`kleague-results`** — [`index.test.js`](https://github.com/NomaDamas/k-skill/blob/main/index.test.js)
- **`kbl-results`** — [`index.test.js`](https://github.com/NomaDamas/k-skill/blob/main/index.test.js) (Korean Basketball League)
- **`korean-marathon-schedule`** — [`index.test.js`](https://github.com/NomaDamas/k-skill/blob/main/index.test.js)

### Government & Legal

- **`court-auction-notice-search`** — [`transport.test.js`](https://github.com/NomaDamas/k-skill/blob/main/transport.test.js), [`normalize.test.js`](https://github.com/NomaDamas/k-skill/blob/main/normalize.test.js), [`index.test.js`](https://github.com/NomaDamas/k-skill/blob/main/index.test.js), [`cli.test.js`](https://github.com/NomaDamas/k-skill/blob/main/cli.test.js)
- **`court-payment-order-assistant`** — [`index.test.js`](https://github.com/NomaDamas/k-skill/blob/main/index.test.js)
- **`local-election-candidate-search`** — [`index.test.js`](https://github.com/NomaDamas/k-skill/blob/main/index.test.js)

### Utility Skills with Multiple Test Files

The `yebigun-training` package demonstrates deeper test coverage:

| Test File | Purpose |
|-----------|---------|
| [`parse.test.js`](https://github.com/NomaDamas/k-skill/blob/main/parse.test.js) | Data parsing logic |
| [`open-menu.test.js`](https://github.com/NomaDamas/k-skill/blob/main/open-menu.test.js) | Menu navigation |
| [`inquiry.test.js`](https://github.com/NomaDamas/k-skill/blob/main/inquiry.test.js) | Query handling |
| [`history.test.js`](https://github.com/NomaDamas/k-skill/blob/main/history.test.js) | State management |
| [`cli-menu.test.js`](https://github.com/NomaDamas/k-skill/blob/main/cli-menu.test.js) | Command-line interface |
| [`browser.test.js`](https://github.com/NomaDamas/k-skill/blob/main/browser.test.js) | Browser automation |

## Runtime and CLI Tests

### k-skill-cli

The command-line interface package validates argument parsing and execution flow:

- **File**: [`packages/k-skill-cli/test/cli.test.js`](https://github.com/NomaDamas/k-skill/blob/main/packages/k-skill-cli/test/cli.test.js)
- **Coverage**: Command-line behavior, runner utilities, error exit codes

### k-skill-browser-runtime

Browser automation tests ensure Puppeteer/Playwright-based skills execute correctly:

- **Files**: [`runtime.test.js`](https://github.com/NomaDamas/k-skill/blob/main/runtime.test.js), [`runner.test.js`](https://github.com/NomaDamas/k-skill/blob/main/runner.test.js)
- **Coverage**: Page navigation, element selection, screenshot capture

## Test Infrastructure and Execution

### Running the Full Suite

The root [`package.json`](https://github.com/NomaDamas/k-skill/blob/main/package.json) defines workspace-aware commands:

```bash

# Install dependencies

npm ci

# Run only unit tests

npm test

# Full CI pipeline (linting + tests)

npm run ci

```

The `npm run ci` command executes tests in parallel across all workspaces, ensuring the monorepo remains healthy on every change.

### Test Framework

- **Primary**: Node.js built-in `node:test` (native since Node 18)
- **Assertions**: `node:assert/strict`
- **Alternative**: Jest where package-specific needs require it

### Mocking Strategy

Tests consistently mock `global.fetch` to:

1. Record outbound URLs for verification
2. Return controlled responses for error scenarios
3. Prevent actual network calls during CI

Example from `k-skill-proxy` tests:

```js
// Setup: Stub fetch before server starts
const originalFetch = global.fetch;
global.fetch = async (url, init) => {
  recordedCalls.push({ url, init });
  return new Response(JSON.stringify(mockBody), { status: 200 });
};

// Teardown: Restore original
test.after(() => { global.fetch = originalFetch; });

```

## Key Source Files Referenced in Tests

| Component | Implementation | Test File |
|-----------|----------------|-----------|
| Server factory | [`src/server.js`](https://github.com/NomaDamas/k-skill/blob/main/src/server.js) | [`test/server.test.js`](https://github.com/NomaDamas/k-skill/blob/main/test/server.test.js) |
| Cache utilities | [`src/cache.js`](https://github.com/NomaDamas/k-skill/blob/main/src/cache.js) | (used across proxy tests) |
| KR WHOIS normalizers | [`src/kr-whois.js`](https://github.com/NomaDamas/k-skill/blob/main/src/kr-whois.js) | [`test/kr-whois.test.js`](https://github.com/NomaDamas/k-skill/blob/main/test/kr-whois.test.js) |
| KOSIS normalizers | [`src/kosis.js`](https://github.com/NomaDamas/k-skill/blob/main/src/kosis.js) | [`test/kosis.test.js`](https://github.com/NomaDamas/k-skill/blob/main/test/kosis.test.js) |
| CLI entry point | [`src/cli.js`](https://github.com/NomaDamas/k-skill/blob/main/src/cli.js) | [`test/cli.test.js`](https://github.com/NomaDamas/k-skill/blob/main/test/cli.test.js) |
| Browser runtime | [`src/runtime.js`](https://github.com/NomaDamas/k-skill/blob/main/src/runtime.js) | [`test/runtime.test.js`](https://github.com/NomaDamas/k-skill/blob/main/test/runtime.test.js) |

## Summary

- **k-skill unit tests** live in `test/` directories under each workspace package
- **40+ skill packages** include dedicated test files, with most using [`index.test.js`](https://github.com/NomaDamas/k-skill/blob/main/index.test.js) as the entry point
- **Core proxy tests** in `k-skill-proxy` validate infrastructure shared by all government API integrations
- **Test execution** uses `npm test` or `npm run ci` for parallel workspace runs
- **Framework**: Native `node:test` with `node:assert/strict`, supplemented by fetch mocking for isolation

## Frequently Asked Questions

### How do I run only the tests for a specific skill package?

Use npm workspaces to target a single package: `npm test -w packages/used-car-price-search`. This executes only that package's `test/` directory without running the full monorepo suite.

### Why does k-skill use `node:test` instead of Jest?

The repository standardizes on Node's built-in test runner to minimize dependencies and reduce maintenance overhead. According to the source analysis, Jest appears only where package-specific requirements demand it.

### What security validations do the unit tests enforce?

Tests verify that **upstream API keys never leak** in responses (see [`kr-whois.test.js`](https://github.com/NomaDamas/k-skill/blob/main/kr-whois.test.js) redaction checks), **sensitive NTS business data is not cached** ([`nts-business.test.js`](https://github.com/NomaDamas/k-skill/blob/main/nts-business.test.js)), and **cache keys are route-scoped** to prevent cross-skill collisions ([`server.test.js`](https://github.com/NomaDamas/k-skill/blob/main/server.test.js)).

### Are integration tests with real APIs included?

No. All tests mock `global.fetch` to avoid external network dependencies. The mock layer records URLs and returns controlled responses, enabling reliable CI execution without API rate limits or availability concerns.