@judo/testing

Shared test utilities and fixtures for JUDO UI Runtime

Purpose

Test infrastructure for the entire monorepo. Loads and caches real example .model files, creates factory objects for data-layer types, resolves actions via ModelRegistry, and offers tree-traversal/assertion helpers for the visual element hierarchy. No React hooks or context providers — this is a pure Node.js/Vitest utility library.

Architecture Layer

Layer 2 (Cross-cutting) — consumed by test suites across all packages.

Dependencies

• @judo/model-api — type definitions
• @judo/model-loader — model loading and registry
• @judo/model-parser — XML parsing

File Structure

src/
├── index.ts                # Barrel re-exports
├── model-loader.ts         # Loads & caches example .model files
├── model-fixtures.ts       # Lazy-getter objects for every example model
├── factories.ts            # Factory functions for data-layer types
├── mock-services.ts        # Action factory helper
├── action-fixtures.ts      # Action resolution & lookup helpers
├── visual-tree.ts          # Visual element tree traversal & assertions
└── *.test.ts               # Tests for each module

Exports Summary

Model Loading

| Export | Kind | Description | | --------------------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------- | | ExampleModelName | type | Union of 8 available example model names: "SimpleOrderManagement", "DebateTest", "CRUDActionsTest", etc. | | loadExampleModel(name) | function | Reads an example .model XML file, parses it, resolves all references, and caches the result. Returns Application[]. | | loadExampleApp(name) | function | Returns the first Application from a model (for single-actor models). | | loadExampleAppByActor(modelName, actorName) | function | Returns the Application whose name matches. Throws with available names on miss. | | clearModelCache() | function | Clears the internal model parse cache for test isolation. | | getAvailableModelNames() | function | Returns the list of all 8 ExampleModelName values. |

Model Fixtures

| Export | Kind | Description | | ---------------- | -------- | ------------------------------------------------------------------------------------ | | EXAMPLE_MODELS | constant | Object with lazy getters — provides Application[] for every example model. | | EXAMPLE_APPS | constant | Object with lazy getters — provides the first Application for every example model. |

Action Fixtures

| Export | Kind | Description | | -------------------------------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | ResolvedAction | interface | A fully-resolved action with xmi:id, name, actionDefinition: ActionDefinition, and optional targetPageDefinition, targetDataElement, ownerDataElement. | | getModelRegistry(modelName) | function | Returns (or creates & caches) a ModelRegistry populated with all applications from an example model. | | resolveAction(modelAction, registry) | function | Converts a model Action to a ResolvedAction. Returns undefined if unresolvable. | | findActionsByType(app, actionType, registry) | function | Collects all ResolvedActions from every page whose actionDefinition.@type matches. | | findFirstActionByType(app, actionType, registry) | function | Returns the first matching resolved action across all pages, or undefined. | | getPageActions(page, registry) | function | Returns all resolved actions from a single page definition. | | getCRUDTestAction(actionType) | function | Shortcut — loads CRUDActionsTest model and finds first action matching the given type. | | getActionGroupTestAction(actionType) | function | Shortcut — loads ActionGroupTest model and finds first action matching the given type. | | clearRegistryCache() | function | Clears the internal registry cache for test isolation. |

Visual Tree Utilities

| Export | Kind | Description | | ------------------------------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------ | | VisualTreeExpectation | interface | Declarative shape for tree assertions: type (required), optional name, sourceId, and recursive children. | | AssertionResult | interface | Result of a tree assertion: passed flag, optional message and path. | | assertVisualTreeResult(actual, expected, path?) | function | Recursively compares a VisualElement tree against expected shape. Returns a detailed AssertionResult (non-throwing). | | assertVisualTree(actual, expected) | function | Throws if the tree doesn't match. Wrapper around assertVisualTreeResult. | | getChildren(element) | function | Extracts child VisualElements from any container. | | findVisualElementByType(root, type) | function | Depth-first search by @type. | | findAllVisualElementsByType(root, type) | function | Collects all elements matching a type (depth-first). | | countVisualElementsByType(root, type) | function | Counts elements of a given type. | | findVisualElementByName(root, name) | function | Depth-first search by name. | | findVisualElementBySourceId(root, sourceId) | function | Depth-first search by sourceId. | | getTreeDepth(element) | function | Returns maximum depth of the visual tree (1-based). | | flattenVisualTree(element) | function | Depth-first flattening into a flat array. |

Data Factories

| Export | Kind | Description | | ----------------------------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------- | | TestClassTypeOptions | interface | Options for createTestClassType. | | createTestClassType(options?) | function | Factory for ClassType with sensible defaults. Auto-generates unique xmi:id. Sets @type to "data:ClassType". | | TestRelationTypeOptions | interface | Options for createTestRelationType. | | createTestRelationType(options?) | function | Factory for RelationType. Defaults: isCollection: true, isOptional: false, relationKind: "ASSOCIATION", memberType: "MAPPED". | | TestAttributeTypeOptions | interface | Options for createTestAttributeType. | | createTestAttributeType(options?) | function | Factory for AttributeType. Defaults: memberType: "MAPPED", isReadOnly: false, isFilterable: true. | | TestDataTypeOptions | interface | Options shared by all DataType factories. | | createTestStringType(options?) | function | Factory for a StringType DataType. Sets @type to "data:StringType". | | createTestNumericType(options?) | function | Factory for a NumericType DataType. Sets @type to "data:NumericType". | | createTestBooleanType(options?) | function | Factory for a BooleanType DataType. Sets @type to "data:BooleanType". | | createTestDateType(options?) | function | Factory for a DateType DataType. Sets @type to "data:DateType". | | createTestTimestampType(options?) | function | Factory for a TimestampType DataType. Sets @type to "data:TimestampType". |

Mock Services

| Export | Kind | Description | | ------------------------------ | -------- | ----------------------------------------------------------------------- | | createTestAction(overrides?) | function | Factory for an Action object. Defaults to a DeleteActionDefinition. |

Key Patterns

• Lazy caching: Model parse results and registry instances are cached in Map-based caches. Lazy getter objects defer parsing until first access.
• Real models, not mocks: All fixtures load actual .model XML files and run them through the full parse → resolve pipeline.
• Cache-clearing for isolation: clearModelCache() and clearRegistryCache() for resetting shared state between test suites.
• Factory functions with defaults: Every factory auto-generates a unique xmi:id. All fields have sensible defaults matching EMF defaults.
• Depth-first tree traversal: All findVisualElement* functions use recursive DFS. getChildren() is the single abstraction for extracting children from containers.
• Non-throwing + throwing assertion variants: assertVisualTreeResult returns a structured result; assertVisualTree wraps it and throws.