Workflow
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 testUseful 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 --prettyTest types#
Messagevisor supports four test subjects:
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.ymlassertions: - locale: en target: web expectedTranslation: Sign inMessage assertions can also use:
contextvalueswithFlagswithVariationscurrencytimeZoneformatsexpectedByRuntimematrix
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.ymlassertions: - context: age: 21 expectedToMatch: trueUse 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
rawMessageplusexpectedTranslation - both at the same time
locale: en-US # references locales/en-US.ymlassertions: - 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:
valuescontextformatscurrencytimeZoneexpectedByRuntimematrix
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:
expectedToIncludeMessagesexpectedToNotIncludeMessagesexpectedFormatsrawMessageplusexpectedTranslationmessageplusexpectedTranslation
target: web # references targets/web.ymlassertions: - 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
messageis 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.welcomeassertions: - 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:
descriptionvaluescontextexpectedTranslationexpectedByRuntimeexpectedFormatscurrencytimeZone
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:
localetargetsegment- 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=stagingThis 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:
- run
test --keyPattern=... - narrow with
--assertionPattern=... - add
--showDatafilefor target-heavy cases - use
evaluateorexampleswhen 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.

