Test metadata
Expose compiled controls to testing and inspection tools through a versioned JSON contract.
Author controls
Controls accept three optional declarations:
| Prop | Type | Default | Description |
|---|---|---|---|
testId | string | absent | Case-sensitive identity, nonblank and at most 256 characters |
testRole | TestRole | inferred | Semantic role for a custom control; does not change its input mechanism |
testName | string | inferred | A 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:
{ "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:
{
"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
| Field | Meaning |
|---|---|
schemaVersion | Version of the JSON contract, also present on each screen |
producer | @bedrock-core/ui-compiler |
files | Resource-pack-relative UI paths and lowercase SHA-256 hashes of their exact bytes |
screens[].file | Generated JSON UI file containing this screen |
screens[].source | Source module provenance; does not contain JSX line locations |
screens[].metadata | Screen 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
- Control props — shared component properties
- ui-compiler stage — settings and generated output