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

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 exercises the buildServer() factory and makeCacheKey() helper:

// 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	Query normalization, API key injection, response caching
KOPIS (Performing Arts)	kopis.test.js	Parameter mapping, semantic error retry logic
KR WHOIS	kr-whois.test.js	Domain/IP/AS normalizers, secret key redaction
NHIS (Health Insurance)	nhis.test.js	Long-term care normalizers, retry on semantic failures
NTS Business	nts-business.test.js	POST body handling, non-caching of sensitive data
Food Safety Korea	food-safety.test.js	XML/JSON handling, key-validation error recovery
KOSIS (Statistics)	kosis.test.js	Six query normalizers (search, meta, data, list, explain, indicator)

Additional proxy tests cover vworld.test.js, region-lookup.test.js, naver-shopping.test.js, naver-news.test.js, molit.test.js, lh-notice.test.js, korean-law.test.js, hrfco.test.js, g2b-order-plan.test.js, ev-charger.test.js, building-register.test.js, and 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, index.test.js (API client behavior)
• daishin-report-search — index.test.js (report retrieval)
• market-kurly-search — index.test.js (e-commerce search)
• daiso-product-search — index.test.js (product catalog)

Location & Public Services

• public-restroom-nearby — index.test.js
• parking-lot-search — index.test.js
• cheap-gas-nearby — index.test.js
• ev-charger — covered in proxy tests; ev-subsidy-status — index.test.js, http.test.js, browser.test.js

Sports & Entertainment

• lck-analytics — index.test.js (League of Legends Champions Korea)
• kleague-results — index.test.js
• kbl-results — index.test.js (Korean Basketball League)
• korean-marathon-schedule — index.test.js

Government & Legal

• court-auction-notice-search — transport.test.js, normalize.test.js, index.test.js, cli.test.js
• court-payment-order-assistant — index.test.js
• local-election-candidate-search — index.test.js

Utility Skills with Multiple Test Files

The yebigun-training package demonstrates deeper test coverage:

Test File	Purpose
parse.test.js	Data parsing logic
open-menu.test.js	Menu navigation
inquiry.test.js	Query handling
history.test.js	State management
cli-menu.test.js	Command-line interface
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
• 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, runner.test.js
• Coverage: Page navigation, element selection, screenshot capture

Test Infrastructure and Execution

Running the Full Suite

The root package.json defines workspace-aware commands:

# 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:

// 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	test/server.test.js
Cache utilities	src/cache.js	(used across proxy tests)
KR WHOIS normalizers	src/kr-whois.js	test/kr-whois.test.js
KOSIS normalizers	src/kosis.js	test/kosis.test.js
CLI entry point	src/cli.js	test/cli.test.js
Browser runtime	src/runtime.js	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 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 redaction checks), sensitive NTS business data is not cached (nts-business.test.js), and cache keys are route-scoped to prevent cross-skill collisions (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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}