exframe-rating

Rating engine build tools and test runner for insurance rating calculations. Supports building rating engines from CSV source files and running integration tests for both v2 and v3 engine versions.

Overview

This package provides:

• Engine Builder: Compile rating engines from CSV factor files and metadata into executable YAML configurations
• Test Runner: Execute integration tests against company packages with support for v2 and v3 rating engines
• CLI Interface: Unified command-line interface for building engines and running tests

Installation

This package is part of the exframe monorepo and is not published separately. It depends on:

• exframe-rating-engine - Rating engine execution (v2 and v3)
• exframe-query-engine - SQL query engine for v3 rating

Commands

build

Build a rating engine YAML file from CSV source files and factor metadata.

node exframe/packages/exframe-rating/index.js build <rateCode> -i <input-dir> -o <output-dir> [-t]

Arguments:

• rateCode - Rate code identifier (e.g., 20240101)

Options:

• -i, --input <directory> - Path to the input directory containing CSV files and metadata
• -o, --output <directory> - Path to the output directory for generated YAML file
• -t, --test - Test mode: display output in console instead of creating file

Example:

node exframe/packages/exframe-rating/index.js build 20240101 \
  -i company-packages/ttic-ct-ho3/engine-sources/20240101/ \
  -o company-packages/ttic-ct-ho3/data/engines/

runTest

Run integration tests for a company package's rating engine.

node exframe/packages/exframe-rating/index.js runTest <package-dir> [options]

Arguments:

• packageDir - Path to the company package directory (relative or absolute)

Options:

• --rerun-failed - Only rerun previously failed tests
• -v, --verbose - Show verbose output including passing tests

Example:

# Run all tests
node exframe/packages/exframe-rating/index.js runTest company-packages/ttic-ct-ho3

# Run with verbose output
node exframe/packages/exframe-rating/index.js runTest company-packages/ttic-ct-ho3 --verbose

# Rerun only failed tests
node exframe/packages/exframe-rating/index.js runTest company-packages/ttic-ct-ho3 --rerun-failed

updateTest

Update test expectations with actual rating results. This is useful when engine logic changes and you need to update the expected premiums in your test data.

node exframe/packages/exframe-rating/index.js updateTest <package-dir> [options]

Arguments:

• packageDir - Path to the company package directory (relative or absolute)

Options:

• --rerun-failed - Only rerun previously failed tests
• -v, --verbose - Show verbose output

Example:

node exframe/packages/exframe-rating/index.js updateTest company-packages/ttic-ct-ho3

Test File Structure

Company packages should follow this structure for testing:

company-package/ ├── data/ │ └── engines/ │ ├── 20240101.yml # Engine version files (YYYYMMDD.yml) │ ├── 20250101.yml │ └── 20260101.yml └── integration-tests/ └── data/ └── rating-engine.csv # Test data

Test CSV Format

The rating-engine.csv file should contain test cases with these columns:

Required Columns:

• skip - Set to "true" to skip this test
• testId - Unique identifier for the test
• type - Description of the test
• expectedPremium - Expected premium result
• effectiveDate - Effective date (determines which engine version to use)

Input Columns: Additional columns representing nested input fields using dot notation:

• property.territory
• property.yearBuilt
• coverageLimits.dwelling.amount
• deductibles.hurricane.amount
• etc.

Engine Version Support

The test runner automatically selects the appropriate engine version based on the test's effective date.

v2 Engine

• Uses lookup-based factors with conditional logic
• Supports JSON-transpose expressions
• Factor calculations with explicit inputs

v3 Engine

• Uses SQL-based queries with relational data
• Supports complex joins and aggregations
• Query engine for factor lookups

Engine Selection Logic

1. Discovers all .yml files in data/engines/ directory
2. Parses effective dates from filenames (YYYYMMDD.yml)
3. For each test, selects the most recent engine not newer than the test's effective date
4. Loads and executes the appropriate engine version

Test Execution

The test runner:

1. Reads test data from integration-tests/data/rating-engine.csv
2. For each test:
   • Formats the document from CSV row data
   • Selects appropriate engine based on effective date
   • Runs the rating engine
   • Compares actual vs expected premium (tolerance: +/- $1)
   • Reports pass/fail status
3. Saves failed test IDs to integration-tests/failed-tests.txt
4. Optionally updates CSV with actual values in fix mode

Usage

You can also use the test runner programmatically:

import { runTests } from 'exframe-rating/lib/test-runner.js';

const results = await runTests('/path/to/company-package', {
  fix: false,           // Update test expectations
  rerunFailed: false,   // Only rerun failed tests
  verbose: false        // Show verbose output
});

console.log(`Total: ${results.total}`);
console.log(`Passed: ${results.passed}`);
console.log(`Failed: ${results.failed}`);
console.log(`Skipped: ${results.skipped}`);

NPM Scripts

Add convenience scripts to your root package.json:

{
  "scripts": {
    "test:rating": "node exframe/packages/exframe-rating/index.js runTest",
    "test:rating:update": "node exframe/packages/exframe-rating/index.js updateTest",
    "build:engine": "node exframe/packages/exframe-rating/index.js build"
  }
}

Then run:

npm run test:rating company-packages/ttic-ct-ho3
npm run test:rating:update company-packages/ttic-ct-ho3
npm run build:engine 20240101 -i company-packages/ttic-ct-ho3/engine-sources/20240101/ -o company-packages/ttic-ct-ho3/data/engines/

Failed Tests

When tests fail, their IDs are automatically added to integration-tests/failed-tests.txt in the package directory. This allows you to:

1. Review which tests failed
2. Rerun only failed tests using --rerun-failed flag
3. Fix issues incrementally without rerunning all tests

The failed tests file is automatically cleared when all tests pass.

License

ISC