Testing Setup with Vitest

Relevant source files

The following files were used as context for generating this wiki page:

• vitest.config.ts
• package.json
• tests/format.test.ts
• tests/label-map.test.ts
• tests/normalize.test.ts
• CHANGELOG.md

The @cellarnode/beverage-utils project utilizes Vitest as its primary testing framework to ensure the reliability of its core utilities and framework-specific adapters. The testing suite is designed to validate the logic of beverage classification mapping, string formatting, and data normalization, ensuring consistent behavior across different environments.

The setup is integrated into the project's development workflow through standard npm scripts, allowing for both one-off execution and continuous monitoring during development via watch mode.

Sources: package.json:52-53, CHANGELOG.md:12

Configuration and Integration

The testing environment is defined by a dedicated configuration file and managed through the project's package manifest.

Vitest Configuration

The project uses vitest.config.ts to define the scope of test execution. The configuration specifies that the test runner should include files located in the __tests__ directory that follow the *.test.ts naming convention.

import { defineConfig } from "vitest/config";

export default defineConfig({
  test: {
    include: ["__tests__/**/*.test.ts"],
  },
});

Sources: vitest.config.ts:1-7

Execution Scripts

Testing is integrated into the standard Node.js development lifecycle via package.json scripts.

Script	Command	Description
test	vitest run	Executes all tests once (CI mode).
test:watch	vitest	Starts the Vitest runner in interactive watch mode.

Sources: package.json:52-53

Testing Architecture

The testing architecture follows a modular approach, where each core utility file in src/ has a corresponding test suite in __tests__/.

The diagram shows the relationship between test files and the source modules they validate. Note that format.test.ts also utilizes label-map.ts logic for complex formatting scenarios.
Sources: tests/format.test.ts:1-3, tests/label-map.test.ts:1-2, tests/normalize.test.ts:1-2

Test Suite Categories

Formatting Tests

The format.test.ts suite validates the transformation of beverage slugs and IDs into human-readable strings. It covers:

• Null Safety: Ensuring empty strings are returned for null or undefined inputs.
• Map Lookups: Verifying that category and subtype IDs are correctly mapped to names.
• Fallback Logic: Ensuring snake_case slugs are humanized when no mapping exists.
• Disambiguation: Testing the "category / subtype" format, particularly how composite keys resolve naming conflicts across different categories.

Sources: tests/format.test.ts:5-52

Label Mapping Tests

The label-map.test.ts suite focuses on the buildLabelMap function, which creates the lookup dictionary for the application. It tests:

• Flat Keys: Mapping category IDs and subtype IDs directly to names.
• Composite Keys: Verifying the creation of category:subtype keys to prevent collisions.
• Last-Write-Wins: Validating behavior when duplicate subtype IDs exist across categories.

Sources: tests/label-map.test.ts:4-44

Normalization Tests

The normalize.test.ts suite ensures data consistency for comparison and storage. It covers three main areas:

Area	Verified Functionality
Token Normalization	Diacritic stripping (e.g., "Côte" to "cote"), whitespace collapsing, and lowercase transformation.
Country Resolution	Mapping English names, ISO alpha-2, and ISO alpha-3 codes to canonical alpha-2 codes.
Volume Parsing	Converting strings like "750ml", "5 kL", or "bottles 750ml × 4000" into numeric liters.

Sources: tests/normalize.test.ts:4-111

Continuous Integration

As noted in the project history, a GitHub Actions CI workflow was introduced to automate the testing process. This workflow triggers on pushes to the main branch, ensuring that all tests pass (along with type-checking and building) before code is considered stable.

Sources: CHANGELOG.md:12-13

Testing is a fundamental part of the @cellarnode/beverage-utils lifecycle, providing a safety net for the core classification logic and its framework adapters (React, Vue, and Angular). By leveraging Vitest's speed and TypeScript support, the project maintains high standards for data accuracy in beverage classification.