Skip to main content

Test metadata

Expose compiled controls to testing and inspection tools through a versioned JSON contract.

Author controls​

Controls accept three optional declarations:

PropTypeDefaultDescription
testIdstringabsentCase-sensitive identity, nonblank and at most 256 characters
testRoleTestRoleinferredSemantic role for a custom control; does not change its input mechanism
testNamestringinferredA declared name for tooling, separate from client-rendered text

Use stable constants. These values are captured at build time and do not track runtime state. Screen, Form, and Container also accept a screen testId. Styled fields forward the declarations to the field rather than its label wrapper.

import { Button, Panel, Screen, Text } from '@bedrock-core/ui';

export default function Settings() {
return (
<Screen testId="settings">
<Panel>
<Button testId="notifications" testRole="checkbox" testName="Notifications">
<Text>Enable alerts</Text>
</Button>
</Panel>
</Screen>
);
}

Roles are screen, button, checkbox, textbox, slider, combobox, listbox, text, image, and group. Duplicate IDs remain separate metadata entries; tools must handle ambiguous matches. Test declarations are independent of a field's name, a control's id, and a slot's role.

Generate metadata​

Enable testMetadata in the ui-compiler stage:

bedrockCore.profiles.default.stages
{ "ui-compiler": { "testMetadata": true } }

The stage writes bedrock-core/test-metadata.json in the selected resource pack. Disabling the option removes that manifest. The UI documents, shared faces, form response ordering, and compiled snapshots are unchanged.

Direct compileScreen and compileFormScreen calls accept the same option and return optional ScreenTestMetadata as compiled.testMetadata.

Import the contract​

The testing entry point can be imported in Node without the Minecraft runtime:

import { TEST_METADATA_PATH, TEST_METADATA_VERSION } from '@bedrock-core/ui-compiler/testing';
import type {
ScreenTestMetadata, TestControlMetadata, TestHost, TestInteraction,
TestMetadataFile, TestMetadataManifest, TestMetadataScreen, TestName, TestRole,
} from '@bedrock-core/ui-compiler/testing';

TEST_METADATA_PATH is resource-pack-relative; TEST_METADATA_VERSION is 1. The package also exports a standalone JSON Schema. Load it through a resolver for use with your JSON Schema validator:

import { readFileSync } from 'node:fs';
import { createRequire } from 'node:module';

const schemaPath = createRequire(import.meta.url).resolve('@bedrock-core/ui-compiler/testing/schema');
const schema = JSON.parse(readFileSync(schemaPath, 'utf8'));

The main compiler entry point re-exports the same constants and metadata types.

Editor schema​

Use test-metadata.schema.json to inspect generated metadata with editor validation. Associate it in VS Code without modifying the generated manifest:

.vscode/settings.json
{
"json.schemas": [{
"fileMatch": ["**/bedrock-core/test-metadata.json"],
"url": "https://bedrock-core.drav.dev/schemas/ui-compiler/beta/test-metadata.schema.json"
}]
}

The beta URL follows current compiler sources. Stable snapshots begin at 1.0.0 under /schemas/ui-compiler/<version>/test-metadata.schema.json. For a local install, url can point to ./node_modules/@bedrock-core/ui-compiler/schemas/test-metadata.schema.json, relative to the workspace root. JSON schemas describes version selection. Schema validation checks the metadata contract; it does not verify client rendering or input.

Manifest fields​

FieldMeaning
schemaVersionVersion of the JSON contract, also present on each screen
producer@bedrock-core/ui-compiler
filesResource-pack-relative UI paths and lowercase SHA-256 hashes of their exact bytes
screens[].fileGenerated JSON UI file containing this screen
screens[].sourceSource module provenance; does not contain JSX line locations
screens[].metadataScreen identity (addon:name), namespace, host, optional screen test ID, and controls

Each control records its generated node, semantic role, optional testId and name, concrete paths, and interaction. Property paths start at the document root, with array indexes encoded as strings. Shared definitions can have distinct inline instance paths. Generated node names and paths describe this build; use authored test IDs as identities across builds.

source is a project-relative module path with forward slashes, or the configured package specifier for a library screen. For shaped app screens, it identifies the manifest script entry used to read the addon registration. Generated shape intermediates are not source identities.

Name kinds distinguish literal text, translated keys, bound values, and authored declarations. testName and styled field captions produce declared names. All names are compiler declarations; an assertion about visible text needs an independent client observation.

Button captions include text inside nested layout and component wrappers. Literal parts combine into one name; a single translated key keeps its translated kind. Mixed literal and translated parts require an explicit testName. A caption that changes across compiled button faces has a bound name containing its initial value. Form.Button labels retain their literal or translated kind, including the default localized caption.

Fixed-capacity list rows have separate compiled paths, including slots hidden by the initial row count. These paths identify compiled slots; tools must independently determine which runtime item occupies a slot.

interaction identifies a concrete form button or native modal mechanism. It does not guarantee that a tool supports an action, that a control is visible or enabled, or that input reaches an application callback. A role override does not change this field. Chest mechanisms and controls without one concrete supported instance use unsupported. Dynamic factories and grids do not imply stable runtime instance identities.

Consume metadata​

Builder refreshes the file list and SHA-256 hashes after all plugin hooks and source exclusions, before final validation and export. Added UI JSON files are included, removed files are omitted, and whitespace changes affect their hashes. Plugin-added fields in the sidecar are retained. Final-artifact hashes are refreshed on cached builds as well.

Tools validate the supported schema version and file hashes before using property paths. Resolve only within the selected resource pack and the matching generated document. Multiple matches require explicit disambiguation; selecting the first match can address the wrong control.

Version 1 permits additional fields so tools can ignore additive metadata. Tools provide their own locators, instrumentation, observation, and input adapters. The compiler contract has no dependency on a particular runner.

Next steps​