@xhubio/nanook-table

Nanook is a toolkit for defining test cases in Excel spreadsheets and generating test data. You describe your test scenarios using equivalence class tables, matrix tables, or specification tables in standard XLSX files, and Nanook reads those definitions, processes them through pluggable data generators, and writes the resulting test data to your chosen output format.

Key Features

• Equivalence class tables -- Define fields, their equivalence classes (valid and invalid), and mark which class applies to each test case.
• Matrix tables -- Describe pairwise or combinatorial relationships between two dimensions of test parameters.
• Specification tables -- Define field rules and severities at a higher level; Nanook automatically converts them into equivalence class tables.
• Pluggable data generators -- Use the built-in Faker generator or write your own. Generators support instance IDs, uniqueness constraints, persistent stores, and post-processing.
• Custom writers -- Control how generated data is written: JSON files, databases, or any format you need.
• Filtering -- Include or exclude test cases at processing time using tag-based filter expressions.
• Single package -- Everything ships as one ESM package with TypeScript types.

Installation

npm install @xhubio/nanook-table

Requires Node.js >= 22.

Quick Start

import path from 'node:path'
import {
  LoggerMemory,
  TestcaseProcessor,
  createDefaultFileProcessor,
  createDefaultGeneratorRegistry,
  createDefaultWriter
} from '@xhubio/nanook-table'

async function main() {
  const logger = new LoggerMemory()
  logger.writeConsole = true

  const fileProcessor = createDefaultFileProcessor(logger)
  const generatorRegistry = createDefaultGeneratorRegistry()

  await fileProcessor.load([path.join('resources', 'tests.xlsx')])

  const tables: Record<string, any> = {}
  for (const table of fileProcessor.tables) {
    tables[table.tableName] = table
  }

  const processor = new TestcaseProcessor({
    logger,
    generatorRegistry,
    writer: [createDefaultWriter(logger)],
    tables
  })

  await processor.process()
}

main()

Data Flow

Excel / XLSX File
    |
    v
ImporterXlsx              -- reads raw cell values
    |
    v
FileProcessor             -- delegates to the right parser per sheet
    |
    +-- ParserDecision     -- sheets starting with <DECISION_TABLE>
    +-- ParserMatrix       -- sheets starting with <MATRIX_TABLE>
    +-- ParserSpecification + ParserSpecificationConverter
    |                         -- sheets starting with <SPECIFICATION_TABLE>
    v
Table Models              -- TableDecision, TableMatrix
    |
    v
TestcaseProcessor         -- orchestrates the generation loop
    |
    +-- DataGeneratorRegistry
    |       +-- GeneratorFaker (built-in)
    |       +-- your custom generators
    |
    +-- InterfaceWriter[]
    |       +-- default JSON writer
    |       +-- your custom writers
    v
Output Files / Data

Table Types

| Marker | Table Type | Description | |---|---|---| | <DECISION_TABLE> | Decision / Equivalence Class | Fields with equivalence classes, one column per test case | | <MATRIX_TABLE> | Matrix | Two-dimensional parameter combinations | | <SPECIFICATION_TABLE> | Specification | High-level rules that convert to a decision table |

Writing a Custom Generator

Extend DataGeneratorBase and override doGenerate():

import {
  DataGeneratorBase,
  DataGeneratorGenerateRequest
} from '@xhubio/nanook-table'

class MyGenerator extends DataGeneratorBase {
  protected async doGenerate(request: DataGeneratorGenerateRequest) {
    const { instanceId, testcaseData, generatorDirective } = request
    // Generate and return your data
    return `generated-value-for-${generatorDirective?.fieldName}`
  }
}

Register it in a DataGeneratorRegistry:

import { DataGeneratorRegistry } from '@xhubio/nanook-table'

const registry = new DataGeneratorRegistry()
const gen = new MyGenerator({ generatorRegistry: registry, name: 'myGen' })
registry.registerGenerator('myGen', gen)

Writing a Custom Writer

Implement the InterfaceWriter interface:

import { LoggerMemory } from '@xhubio/nanook-table'
import type { InterfaceWriter, TestcaseDataInterface } from '@xhubio/nanook-table'

const writer: InterfaceWriter = {
  logger: new LoggerMemory(),
  async before() { /* setup */ },
  async write(testcaseData: TestcaseDataInterface) {
    console.log(`Test case: ${testcaseData.name}`, testcaseData.data)
  },
  async after() { /* cleanup */ }
}

Documentation

See the docs/ directory for detailed guides, API reference, and tutorials:

• API Reference -- Every public class, interface, and function
• Guides -- Conceptual explanations of tables, directives, and generators
• Tutorials -- Step-by-step walkthroughs

Development

npm install          # install dependencies
npm run build        # compile TypeScript
npm test             # run tests (vitest)
npm run lint         # run eslint
npm run format       # run prettier
npm run typecheck    # type-check without emitting

License

MIT