Testing

Messagevisor projects can include authored tests as a built-in feature. They live alongside your definitions and are designed to validate both structure and runtime behavior.

Run tests#

$ npx messagevisor test

Useful filters:

$ npx messagevisor test --keyPattern=welcome
$ npx messagevisor test --assertionPattern=translation
$ npx messagevisor test --onlyFailures
$ npx messagevisor test --showDatafile
$ npx messagevisor test --verbose
$ npx messagevisor test --json --pretty

Test types#

Messagevisor supports four test subjects:

• message
• segment
• locale
• target

Each test file has one subject at the top and an assertions array below it.

Message tests#

Message tests validate resolved translations for one message key.

message: auth.signin # references messages/auth/signin.yml
assertions:
  - locale: en
    target: web
    expectedTranslation: Sign in

Message assertions can also use:

• context
• values
• withFlags
• withVariations
• currency
• timeZone
• formats
• expectedByRuntime
• matrix

Use message tests when you want a crisp pass/fail answer for one message's behavior.

Segment tests#

Segment tests validate whether a segment matches for a given context.

segment: adult # references segments/adult.yml
assertions:
  - context:
      age: 21
    expectedToMatch: true

Use segment tests when:

• a segment is reused in many overrides
• a condition tree is complicated enough that you want direct regression coverage

Locale tests#

Locale tests validate locale-specific behavior independently of a single message definition.

They can assert:

• resolved formats via expectedFormats
• raw-message translation via rawMessage plus expectedTranslation
• both at the same time

locale: en-US # references locales/en-US.yml
assertions:
  - description: Currency preset and translation
    target: preview
    expectedFormats:
      number:
        money:
          currency: USD
    rawMessage: "Total: {amount, number, money}"
    values:
      amount: 19.99
    expectedTranslation: "Total: $19.99"

Locale assertions can also include:

• values
• context
• formats
• currency
• timeZone
• expectedByRuntime
• matrix

Important behavior:

• raw-message translation uses the same module-aware runtime path as the rest of Messagevisor

Target tests#

Target tests validate one target for one or more locales.

They can assert:

• expectedToIncludeMessages
• expectedToNotIncludeMessages
• expectedFormats
• rawMessage plus expectedTranslation
• message plus expectedTranslation

target: web # references targets/web.yml
assertions:
  - locale: en-US # references locales/en-US.yml
    expectedToIncludeMessages:
      - auth.signin
    rawMessage: "Total: {amount, number, money}"
    values:
      amount: 19.99
    expectedTranslation: "Total: $19.99"

Important behavior:

• target assertions build the real target+locale datafile before evaluating
• if message is used and the target excludes that message, the assertion still follows normal SDK behavior instead of using a custom failure path

Matrix expansion#

Assertions can optionally define a matrix to expand one authored assertion into many concrete assertions.

Placeholders use ${{ variableName }} and are resolved before execution.

message: common.welcome
assertions:
  - matrix:
      name: [Ada, Sam]
    locale: en
    target: web
    description: Greeting ${{ name }}
    values:
      name: ${{ name }}
    expectedTranslation: Hello ${{ name }}

What matrix placeholders usually apply to#

They work well in:

• description
• values
• context
• expectedTranslation
• expectedByRuntime
• expectedFormats
• currency
• timeZone

timeZone uses the same spelling as SDK calls, examples, and Intl-shaped format presets. Values are passed to Intl.DateTimeFormat during date/time evaluation.

What stays literal#

Referenced keys usually stay literal in v1, including fields such as:

• locale
• target
• segment
• expected message-key arrays

This keeps key references stable and avoids making a single test file act like a code generator.

Sets-aware testing#

For sets-based projects:

$ npx messagevisor test --set=staging

This is especially useful when:

• definitions differ between sets
• promotions are part of your workflow
• you want to validate one environment before build or deploy

Debugging with tests#

If you are chasing a surprising runtime result:

1. run test --keyPattern=...
2. narrow with --assertionPattern=...
3. add --showDatafile for target-heavy cases
4. use evaluate or examples when you want ad hoc exploration instead of a committed assertion

Edge cases and behavior notes#

Tests vs examples#

• tests are assertions
• examples are documentation and inspection artifacts

If you want the team to understand how something behaves, author both when the behavior matters.

Assertion context vs target context#

• target context shapes the built datafile
• assertion context is passed at evaluation time

This distinction matters most for target tests and locale tests that use a target.

Raw-message tests still depend on modules#

If a locale or target assertion evaluates ICU syntax or interpolation syntax, registered project modules still control how that raw message is interpreted.

Related#

• CLI
• Messages
• Locales
• Targets
• Segments
• Examples
• Evaluation
• Catalog