Label Map Test Coverage

Relevant source files

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

• __tests__/label-map.test.ts
• __tests__/format.test.ts
• src/label-map.ts
• src/format.ts
• src/types.ts
• vitest.config.ts

The label map test coverage ensures the integrity of the beverage classification system used in the CellarNode platform. It focuses on validating the buildLabelMap utility, which transforms complex hierarchical beverage data into flat lookup tables, and the subsequent formatting utilities that consume these maps to provide human-readable labels.

The testing suite utilizes Vitest to verify that beverage categories and subtypes are correctly mapped, specifically handling edge cases such as ID collisions and composite key generation. This coverage is critical for maintaining unambiguous display strings across various frontend adapters.
Sources: tests/label-map.test.ts, README.md:19-27

Core Logic and Data Mapping

The primary component under test is the buildLabelMap function. This function processes a BeverageClassification object to create a LabelMap, which is a flat Record<string, string>. The mapping logic follows a specific hierarchy to ensure both convenience and precision in lookups.

Mapping Strategy

As evidenced by the test suite, the mapping process performs three distinct actions for every category and subtype:

1. Category ID Mapping: Maps a category ID (e.g., "wine") to its display name ("Still Wine").
2. Subtype ID Mapping: Maps a subtype ID (e.g., "red") to its display name ("Red Wine").
3. Composite Key Mapping: Creates a unique key by joining the category and subtype IDs with a colon (e.g., "wine:red") to prevent ambiguity when subtype IDs are reused across different categories.

Sources: src/label-map.ts:5-15, tests/label-map.test.ts:16-25

The diagram above illustrates how hierarchical classification data is flattened into three distinct lookup patterns within the LabelMap.
Sources: src/label-map.ts:5-15, src/types.ts:1-13

Disambiguation and Conflict Resolution

A key focus of the test coverage is the handling of identical subtype IDs belonging to different categories. In the CellarNode system, a subtype like "red" may exist under both "Still Wine" and "Sparkling Wine" but represent different display names.

Test Case	Input Category	Input Subtype	Expected Result	Logic
Flat ID Lookup	N/A	red	Last-write-wins	The last subtype encountered in the loop overwrites previous flat keys.
Composite Lookup	wine	red	Red Wine	Uses wine:red for unique identification.
Composite Lookup	sparkling_wine	red	Red Sparkling	Uses sparkling_wine:red for unique identification.

Sources: tests/label-map.test.ts:27-38, README.md:39-42

Disambiguation Flow

The following sequence demonstrates how the testing suite verifies that the formatBeverageType utility uses the LabelMap to resolve these types correctly.

Formatting Utility Integration

The tests in format.test.ts validate how the application behaves when a LabelMap is either present or missing. This ensures the system remains resilient even if classification data fails to load.

Fallback Mechanisms

• Humanization: When no map is provided or a key is missing from the map, the system "humanizes" the slug by replacing underscores with spaces and converting to Title Case (e.g., sparkling_wine becomes Sparkling Wine).
• Null Safety: The formatBeverageLabel function is tested to return an empty string when provided with null or undefined instead of throwing errors.

Sources: src/format.ts:3-11, tests/format.test.ts:7-21

Key Functions Under Test

Function	File	Description
buildLabelMap	src/label-map.ts	Constructs the lookup table from raw JSON classification data.
formatBeverageLabel	src/format.ts	Formats a single slug using a map or fallback logic.
formatBeverageType	src/format.ts	Combines category and subtype into a display string (e.g., "Cat / Sub").

Sources: src/label-map.ts:5, src/format.ts:3, src/format.ts:13

Test Configuration and Execution

The project uses a standard Vitest configuration. Tests are isolated in the __tests__ directory and target the source files within src/.

// vitest.config.ts
import { defineConfig } from "vitest/config";

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

Sources: vitest.config.ts:1-7

Testing is executed via the npm test command, which runs vitest run. The suite ensures that the BeverageClassification structure—consisting of categories, subtypes, and optional fields like hsHeading or oivType—is correctly handled by the transformation logic.
Sources: package.json:44, src/types.ts:1-13

Summary

Label Map Test Coverage ensures that the beverage classification flattening logic is robust against ID collisions and provides reliable fallbacks. By verifying the creation of composite keys (category:subtype), the tests guarantee that users see accurate labels even when underlying database IDs overlap across different beverage categories.