Skip to content

A platform for community discussion. Free, open, simple.

DEV: Enforce workflow node output contracts in specs (#44554)

Régis Hanolf7f08d9ef1f1
diff --git a/.skills/discourse-workflow-nodes/SKILL.md b/.skills/discourse-workflow-nodes/SKILL.md
index e2c71b05956..63b586f8f2c 100644
--- a/.skills/discourse-workflow-nodes/SKILL.md
+++ b/.skills/discourse-workflow-nodes/SKILL.md
@@ -22,7 +22,7 @@ Shape entities only with `DiscourseWorkflows::EntitySerializers` (`lib/discourse
- Name every helper that shapes an entity for output `serialize_<entity>` (`serialize_badge`, `serialize_group`, `serialize_timer`, `serialize_assignee`, `serialize_channel`, `serialize_event`...), never `<entity>_data`; `node_entity_builders_spec` fails on `def <entity>_data`.
- Don't wrap a shared builder in a node-private helper; call it directly.
-- `serialize_topic_list_item` (`DiscourseWorkflows::TopicListItemSerializer`) carries plugin-added list fields (assign `assigned_to_*`, solved `has_accepted_answer`, voting `can_vote`/`vote_count`...); `serialize_topic` (`DiscourseWorkflows::TopicSerializer`) adds posters, participants and custom fields.
+- `serialize_topic_list_item` (`DiscourseWorkflows::TopicListItemSerializer`) carries plugin-added list fields (assign `assigned_to_*`, solved `has_accepted_answer`, voting `can_vote`/`vote_count`...); `serialize_topic` (`DiscourseWorkflows::TopicSerializer`) adds posters, participants and custom fields. Both emit every `TOPIC_PROPERTIES` key.
- Outside a `NodeType`, call them on the module: `DiscourseWorkflows::EntitySerializers.serialize_user(...)`.
- Never use `BasicUserSerializer` or `TopicListItemSerializer` in node files; `node_entity_builders_spec` fails if you do.
- Groups: `BasicGroupSerializer` (`BASIC_GROUP_PROPERTIES`) or `WebHookGroupSerializer` (`GROUP_SCHEMA`).
@@ -33,3 +33,21 @@ Shape entities only with `DiscourseWorkflows::EntitySerializers` (`lib/discourse
- Actions that may no-op output `changed` (boolean), computed by comparing state before and after (see badge, group, post_like).
- Actions that mutate a topic also return `topic`.
- Cap user lists with a named constant (e.g. `PostEventScoping::MAX_GOING_USERNAMES`).
+
+## Output contracts
+
+`node_output_contracts_spec` has a `user_defined_output` opt-out list. A node belongs there only if the user writes its output shape (code, sql, set_fields, workflow_call, manual). If the shape can be derived from config, override `self.output_schemas` instead.
+
+- Use `"type": [..., "null"]` for keys that are always emitted but may be nil.
+- Use `"x-optional": true` for keys that are only emitted on some paths, such as DM-only `usernames`, or `tags` when the guardian can't see them. Optional objects may be `{}`.
+- `schema_serializer_sync_spec` fails when a declared serializer key is never emitted.
+
+## Specs
+
+Every node spec asserts the real output against the declared contract:
+
+```ruby
+expect(output).to match_node_output_schema(DiscourseWorkflows::Nodes::Foo::V1, configuration: config)
+```
+
+The matcher is strict: every declared property is required unless `x-optional`, and types must match. Run plugin specs with `LOAD_PLUGINS=1 bin/rspec`.
diff --git a/plugins/chat/lib/discourse_workflows/nodes/send_chat_message/v1.rb b/plugins/chat/lib/discourse_workflows/nodes/send_chat_message/v1.rb
index 9aad68bd303..9fc6646280c 100644
--- a/plugins/chat/lib/discourse_workflows/nodes/send_chat_message/v1.rb
+++ b/plugins/chat/lib/discourse_workflows/nodes/send_chat_message/v1.rb
@@ -51,12 +51,14 @@ if defined?(DiscourseWorkflows)
},
"username" => {
"type" => "string",
+ "x-optional" => true,
},
"usernames" => {
"type" => "array",
"items" => {
"type" => "string",
},
+ "x-optional" => true,
},
},
},
diff --git a/plugins/discourse-ai/discourse_workflows/nodes/classify/v1.rb b/plugins/discourse-ai/discourse_workflows/nodes/classify/v1.rb
index 2078e539cc6..b88399443a8 100644
--- a/plugins/discourse-ai/discourse_workflows/nodes/classify/v1.rb
+++ b/plugins/discourse-ai/discourse_workflows/nodes/classify/v1.rb
@@ -180,6 +180,7 @@ if defined?(DiscourseWorkflows)
properties["level"] = { "type" => "string" }
end
end
+ properties.each { |key, property| property["x-optional"] = true if key != "type" }
{ "type" => "object", "properties" => properties }
end
diff --git a/plugins/discourse-assign/lib/discourse_assign/workflows/schema.rb b/plugins/discourse-assign/lib/discourse_assign/workflows/schema.rb
index a45b4731758..61fdde16f03 100644
--- a/plugins/discourse-assign/lib/discourse_assign/workflows/schema.rb
+++ b/plugins/discourse-assign/lib/discourse_assign/workflows/schema.rb
@@ -7,7 +7,7 @@ module DiscourseAssign
"$schema" => DiscourseWorkflows::Schema::DRAFT_URI,
"type" => "object",
"properties" => {
- "assignee" => DiscourseWorkflows::Schema::ASSIGNEE_PROPERTIES,
+ "assignee" => DiscourseWorkflows::Schema::ASSIGNEE_PROPERTIES.merge("x-optional" => true),
"previously_assigned" => DiscourseWorkflows::Schema::ASSIGNEE_PROPERTIES,
},
}.freeze
diff --git a/plugins/discourse-workflows/lib/discourse_workflows/schema.rb b/plugins/discourse-workflows/lib/discourse_workflows/schema.rb
index 4398e411225..20c27afb081 100644
--- a/plugins/discourse-workflows/lib/discourse_workflows/schema.rb
+++ b/plugins/discourse-workflows/lib/discourse_workflows/schema.rb
@@ -57,6 +57,7 @@ module DiscourseWorkflows
"username": { "type": ["string", "null"], "description": "Username of the topic author" },
"tags": {
"type": "array",
+ "x-optional": true,
"items": {
"type": "object",
"properties": {
@@ -68,7 +69,7 @@ module DiscourseWorkflows
},
"first_post_id": { "type": ["integer", "null"] },
"visible": { "type": "boolean" },
- "visibility_reason_id": { "type": "integer" },
+ "visibility_reason_id": { "type": "integer", "x-optional": true },
"closed": { "type": "boolean" },
"archived": { "type": "boolean" },
"created_at": { "type": "string", "format": "date-time" },
@@ -81,11 +82,11 @@ module DiscourseWorkflows
{
"id": { "type": "integer" },
"raw": { "type": "string" },
- "raw_truncated": { "type": "boolean" },
- "raw_original_length": { "type": "integer" },
- "cooked": { "type": "string" },
- "cooked_truncated": { "type": "boolean" },
- "cooked_original_length": { "type": "integer" },
+ "raw_truncated": { "type": "boolean", "x-optional": true },
+ "raw_original_length": { "type": "integer", "x-optional": true },
+ "cooked": { "type": "string", "x-optional": true },
+ "cooked_truncated": { "type": "boolean", "x-optional": true },
+ "cooked_original_length": { "type": "integer", "x-optional": true },
"post_number": { "type": "integer" },
"post_type": { "type": "integer" },
"reply_to_post_number": { "type": ["integer", "null"] },
@@ -304,7 +305,7 @@ module DiscourseWorkflows
"query": { "type": "object" },
"method": { "type": "string" },
"webhook_url": { "type": "string" },
- "raw_body": { "type": "string" }
+ "raw_body": { "type": "string", "x-optional": true }
}
JSON
diff --git a/plugins/discourse-workflows/spec/lib/discourse_workflows/executor/error_workflow_trigger_spec.rb b/plugins/discourse-workflows/spec/lib/discourse_workflows/executor/error_workflow_trigger_spec.rb
index a38a15801cd..38a4b2fe7d8 100644
--- a/plugins/discourse-workflows/spec/lib/discourse_workflows/executor/error_workflow_trigger_spec.rb
+++ b/plugins/discourse-workflows/spec/lib/discourse_workflows/executor/error_workflow_trigger_spec.rb
@@ -144,15 +144,14 @@ RSpec.describe DiscourseWorkflows::Executor::ErrorWorkflowTrigger do
trigger_data =
Jobs::DiscourseWorkflows::ExecuteWorkflow.jobs.last["args"].first["trigger_data"]
- expect(trigger_data["workflow"]).to include("id" => be_present, "name" => be_present)
expect(trigger_data["execution"]).to include(
"id" => be_present,
"url" => include("/admin/plugins/discourse-workflows/workflows/"),
- "retryOf" => nil,
"error" => include("message" => "something broke", "name" => "StandardError"),
"lastNodeExecuted" => "My Node",
"mode" => "trigger",
)
+ expect(trigger_data).to match_node_output_schema(DiscourseWorkflows::Nodes::Error::V1)
end
it "passes the failed run's trigger data through so the error workflow can re-drive it" do
diff --git a/plugins/discourse-workflows/spec/lib/discourse_workflows/match_node_output_schema_spec.rb b/plugins/discourse-workflows/spec/lib/discourse_workflows/match_node_output_schema_spec.rb
index 6d7df061b47..8e3b4097219 100644
--- a/plugins/discourse-workflows/spec/lib/discourse_workflows/match_node_output_schema_spec.rb
+++ b/plugins/discourse-workflows/spec/lib/discourse_workflows/match_node_output_schema_spec.rb
@@ -102,6 +102,41 @@ RSpec.describe RSpec::Matchers, "#match_node_output_schema" do
)
end
+ describe "strict mode" do
+ let(:loose_node) do
+ Class.new do
+ def self.output_schemas(_configuration = {}, input_schemas: [])
+ [
+ {
+ "type" => "object",
+ "properties" => {
+ "name" => {
+ "type" => "string",
+ },
+ "extra" => {
+ "type" => "object",
+ "x-optional" => true,
+ },
+ },
+ },
+ ]
+ end
+ end
+ end
+
+ it "requires declared properties even when the schema omits required" do
+ output = { extra: {} }
+
+ expect(output).not_to match_node_output_schema(loose_node)
+ end
+
+ it "allows x-optional properties to be absent" do
+ output = { name: "Ada" }
+
+ expect(output).to match_node_output_schema(loose_node)
+ end
+ end
+
it "rejects non-Hash output" do
output = [{ profile: { name: "Ada" } }]
diff --git a/plugins/discourse-workflows/spec/lib/discourse_workflows/node_output_contracts_spec.rb b/plugins/discourse-workflows/spec/lib/discourse_workflows/node_output_contracts_spec.rb
index 2b1705a35c3..b9bf4f3f939 100644
--- a/plugins/discourse-workflows/spec/lib/discourse_workflows/node_output_contracts_spec.rb
+++ b/plugins/discourse-workflows/spec/lib/discourse_workflows/node_output_contracts_spec.rb
@@ -23,6 +23,34 @@ RSpec.describe DiscourseWorkflows::NodeType do
expect(overriding.reject(&:output_schema_resolver)).to be_empty
end
+ it "requires every node without a user-defined output to declare it" do
+ user_defined_output = %w[
+ action:code
+ action:data_table
+ action:form
+ action:modal
+ action:set_fields
+ action:split_out
+ action:sql
+ action:workflow_call
+ flow:sticky_note
+ trigger:form
+ trigger:manual
+ trigger:workflow_call
+ ]
+
+ undeclared =
+ DiscourseWorkflows::Registry
+ .nodes(include_disabled_plugins: true)
+ .select do |node_class|
+ next false if user_defined_output.include?(node_class.identifier)
+ next false if node_class.singleton_class.instance_methods(false).include?(:output_schemas)
+ Array(node_class.description.fetch(:output_contracts)).empty?
+ end
+
+ expect(undeclared.map(&:identifier)).to be_empty
+ end
+
it "preserves declarations through nodes that only forward or reorder items" do
node_classes = [
DiscourseWorkflows::Nodes::Log::V1,
diff --git a/plugins/discourse-workflows/spec/lib/discourse_workflows/nodes/http_request_spec.rb b/plugins/discourse-workflows/spec/lib/discourse_workflows/nodes/http_request_spec.rb
index bce1a517af5..84970c8a54d 100644
--- a/plugins/discourse-workflows/spec/lib/discourse_workflows/nodes/http_request_spec.rb
+++ b/plugins/discourse-workflows/spec/lib/discourse_workflows/nodes/http_request_spec.rb
@@ -42,7 +42,7 @@ RSpec.describe DiscourseWorkflows::Nodes::HttpRequest::V1 do
"headers" => include("content-type" => "application/json"),
"status_code" => 200,
)
- expect(result).to have_key("status_message")
+ expect(result).to match_node_output_schema(described_class, configuration: config)
end
it "splits top-level JSON array responses into separate output items" do
diff --git a/plugins/discourse-workflows/spec/lib/discourse_workflows/nodes/post_edited/v1_spec.rb b/plugins/discourse-workflows/spec/lib/discourse_workflows/nodes/post_edited/v1_spec.rb
index 07237020227..1eb50bfa111 100644
--- a/plugins/discourse-workflows/spec/lib/discourse_workflows/nodes/post_edited/v1_spec.rb
+++ b/plugins/discourse-workflows/spec/lib/discourse_workflows/nodes/post_edited/v1_spec.rb
@@ -66,8 +66,6 @@ RSpec.describe DiscourseWorkflows::Nodes::PostEdited::V1 do
)
expect(output[:revision][:changes]).to include("raw")
expect(output).to match_node_output_schema(described_class)
- editor_schema = described_class.output_schemas.first.dig("properties", "editor")
- expect(editor_schema).to include("properties" => DiscourseWorkflows::Schema::USER_PROPERTIES)
end
it "returns post and topic data" do
diff --git a/plugins/discourse-workflows/spec/lib/discourse_workflows/nodes/topic_spec.rb b/plugins/discourse-workflows/spec/lib/discourse_workflows/nodes/topic_spec.rb
index af9cb82a937..3fd5d1ac9d6 100644
--- a/plugins/discourse-workflows/spec/lib/discourse_workflows/nodes/topic_spec.rb
+++ b/plugins/discourse-workflows/spec/lib/discourse_workflows/nodes/topic_spec.rb
@@ -562,16 +562,12 @@ RSpec.describe DiscourseWorkflows::Nodes::Topic::V1 do
expect(topic_data["tags"].map { |topic_tag| topic_tag["name"] }).to contain_exactly(
tag.name,
)
- expect(topic_data["posts_count"]).to be_present
- expect(topic_data["views"]).to be_present
- expect(topic_data["like_count"]).to be_present
- expect(topic_data["created_at"]).to be_present
- expect(topic_data["bumped_at"]).to be_present
expect(post_data).to include(
"id" => topic_1.first_post.id,
"topic_id" => topic_1.id,
"trust_level" => user.trust_level,
)
+ expect(topic_entry).to match_node_output_schema(described_class)
end
it "preloads selected custom fields when requested" do
diff --git a/plugins/discourse-workflows/spec/support/matchers/match_node_output_schema.rb b/plugins/discourse-workflows/spec/support/matchers/match_node_output_schema.rb
index 6140b11807e..882b78f9ff0 100644
--- a/plugins/discourse-workflows/spec/support/matchers/match_node_output_schema.rb
+++ b/plugins/discourse-workflows/spec/support/matchers/match_node_output_schema.rb
@@ -2,26 +2,43 @@
RSpec::Matchers.define :match_node_output_schema do |node_class, configuration: {}, input_schemas: [], output_index: 0|
match do |output|
- @resolved_schema = nil
- @validation_errors = []
- @non_hash_output = !output.is_a?(Hash)
+ next false if (@non_hash_output = !output.is_a?(Hash))
- if @non_hash_output
- false
- else
- @resolved_schema =
- node_class.output_schemas(configuration, input_schemas: input_schemas)[output_index] || {}
-
- if @resolved_schema.blank?
- false
- else
- @validation_errors =
- JSONSchemer.schema(@resolved_schema).validate(output.deep_stringify_keys).to_a
- @validation_errors.empty?
+ @resolved_schema =
+ node_class.output_schemas(configuration, input_schemas: input_schemas)[output_index] || {}
+ next false if @resolved_schema.blank?
+
+ @validation_errors =
+ JSONSchemer
+ .schema(require_declared_properties(@resolved_schema))
+ .validate(output.deep_stringify_keys)
+ .to_a
+ @validation_errors.empty?
+ end
+
+ def require_declared_properties(schema)
+ case schema
+ when Hash
+ strict = schema.transform_values { |value| require_declared_properties(value) }
+ return strict if !schema["properties"].is_a?(Hash)
+
+ strict["required"] = schema["properties"].reject { |_, value| optional?(value) }.keys
+ strict["properties"] = strict["properties"].to_h do |name, value|
+ next name, value if !optional?(value) || value["type"] != "object"
+ [name, { "anyOf" => [{ "type" => "object", "maxProperties" => 0 }, value] }]
end
+ strict
+ when Array
+ schema.map { |value| require_declared_properties(value) }
+ else
+ schema
end
end
+ def optional?(schema)
+ schema.is_a?(Hash) && schema["x-optional"]
+ end
+
failure_message do |output|
node_name = node_class.name.presence || node_class.to_s