This is an automated email from the ASF dual-hosted git repository. davsclaus pushed a commit to branch CAMEL-26609-dst-worlds-docs in repository https://gitbox.apache.org/repos/asf/camel.git
commit cd232c3c76c12bd1bdbf53cadda77a4090fa623b Author: Claus Ibsen <[email protected]> AuthorDate: Thu Nov 12 22:04:26 2026 +0100 CAMEL-26609: docs - the component pages show their DST worlds in a Deterministic simulation tests section The pages of a component with fake worlds (the dstWorlds section of its JSON, CAMEL-26438) get a "Deterministic simulation tests" section, from the shared partial every component page includes, as the Message Body section does: no component page is edited, and the section only shows when the component has a world. Per world: its simple name (the world is a test class in no JAR), the fake, the tests, what it covers, the faults it injects, the invariants it checks and the JIRA issues; and links to the camel-test-dst page. Co-Authored-By: Claude Opus 5.5 <[email protected]> Signed-off-by: Claus Ibsen <[email protected]> --- docs/components/modules/ROOT/examples/js/camel.js | 35 ++++++++++++++++++++++ .../ROOT/partials/component-endpoint-headers.adoc | 2 ++ .../modules/ROOT/partials/dst-worlds.adoc | 23 ++++++++++++++ 3 files changed, 60 insertions(+) diff --git a/docs/components/modules/ROOT/examples/js/camel.js b/docs/components/modules/ROOT/examples/js/camel.js index 6fd0f85c4983..a59a7e31f31e 100644 --- a/docs/components/modules/ROOT/examples/js/camel.js +++ b/docs/components/modules/ROOT/examples/js/camel.js @@ -115,4 +115,39 @@ module.exports = { } return parts.join('\n\n') }, + + // the fake worlds of the deterministic simulation tests (CAMEL-26438, CAMEL-26609): one row per world of the + // dstWorlds section. The world is a test class in no JAR, so it is shown by its simple name, not linked. + dstWorld: (name, value) => { + const parts = ['`' + name + '`'] + if (value.fake) { + parts.push('Fake: ' + module.exports.dstEscape(value.fake)) + } + if (value.tests && value.tests.length) { + parts.push('Tests: ' + value.tests.map((test) => '`' + test + '`').join(', ')) + } + return parts.join('\n\n') + }, + + // what the world covers, the faults it injects and the invariants it checks, each as a list + dstChecks: (value) => { + const list = (title, items) => (items && items.length) + ? `*${title}:*\n\n` + items.map((item) => '* ' + module.exports.dstEscape(item)).join('\n') + : '' + return [list('Covers', value.covers), list('Faults', value.faults), list('Invariants', value.invariants)] + .filter((part) => part) + .join('\n\n') + }, + + // the JIRA issues of the world, as links + dstIssues: (value) => { + return (value.issues || []) + .map((issue) => `https://issues.apache.org/jira/browse/${issue}[${issue}]`) + .join('\n\n') + }, + + // what reads as an attribute reference ({name}), and the cell separator + dstEscape: (text) => { + return text.replace(/\{(\w[\w-]*)\}/g, '\\{$1}').split('|').join('\\|') + }, } diff --git a/docs/components/modules/ROOT/partials/component-endpoint-headers.adoc b/docs/components/modules/ROOT/partials/component-endpoint-headers.adoc index dac98068db71..765bbe0228ae 100644 --- a/docs/components/modules/ROOT/partials/component-endpoint-headers.adoc +++ b/docs/components/modules/ROOT/partials/component-endpoint-headers.adoc @@ -25,3 +25,5 @@ endif::[] :body-types-module: ROOT :body-types-intro: The message body at each side of the {doctitle} component: _Consumer_ is the body of the messages the consumer creates, _Consumer reply_ the bodies a consumer that answers its caller can reply with, _Producer input_ the bodies the producer can send or write, and _Producer output_ the body after the producer. include::partial$body-types.adoc[] + +include::partial$dst-worlds.adoc[] diff --git a/docs/components/modules/ROOT/partials/dst-worlds.adoc b/docs/components/modules/ROOT/partials/dst-worlds.adoc new file mode 100644 index 000000000000..ce525a411fb0 --- /dev/null +++ b/docs/components/modules/ROOT/partials/dst-worlds.adoc @@ -0,0 +1,23 @@ +// dst worlds: START +// the fake worlds of the deterministic simulation tests of the component, from the dstWorlds section of its JSON +include::jsonpathcount$example$json/{shortname}.json[queries='dstworldcount=nodes$.dstWorlds.*'] + +ifeval::[{dstworldcount} != 0] +== Deterministic simulation tests + +The consumer of the {doctitle} component is tested with xref:others:test-dst.adoc[deterministic simulation tests]: +the real consumer runs under a seeded virtual-time scheduler against a fake of the external system, which injects +faults while the tests check invariants. A failing seed can be replayed. These are the fake worlds of the component: + +[width="100%",cols="3a,6a,2a",options="header"] +|=== +| World | What it checks | Issues +|=== + +jsonpathTable::example$json/{shortname}.json['nodes$.dstWorlds.*','camel.dstWorld(path[2], value)|camel.dstChecks(value)|camel.dstIssues(value)','camel=xref:ROOT:js/camel.js'] + +The worlds and their tests are in the test sources of the component. How to run them, replay a seed and write a +world is described in xref:others:test-dst.adoc#_running_the_tests[Running the tests] and +xref:others:test-dst.adoc#_writing_a_fake_world_a_guide_for_ai_agents_and_humans[Writing a fake world]. +endif::[] +// dst worlds: END
