Skip to content

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

DEV: Improve JSON schema failure output in API specs (#41182)

Martin Brennancd98d818dcb2
diff --git a/spec/requests/api/shared/shared_examples.rb b/spec/requests/api/shared/shared_examples.rb
index 48a0e8878c0..a76c44783b3 100644
--- a/spec/requests/api/shared/shared_examples.rb
+++ b/spec/requests/api/shared/shared_examples.rb
@@ -17,34 +17,139 @@ RSpec.shared_examples "a JSON endpoint" do |expected_response_status|
end
end
- def expect_schema_valid(schemer, params)
- valid = schemer.valid?(params)
-
- unless valid
- validation_result = schemer.validate(params).to_a[0]
- pointer = validation_result["data_pointer"]
-
- if pointer.present?
- at_pointer = value_at_json_pointer(params, pointer)
- puts "VALUE AT #{pointer.inspect}: #{at_pointer.inspect}"
- parent_pointer = pointer.sub(%r{/[^/]+\z}, "")
- if parent_pointer != pointer && parent_pointer.present?
- parent = value_at_json_pointer(params, parent_pointer)
- puts "PARENT AT #{parent_pointer.inspect}: #{parent.inspect}"
- end
- else
- puts "RESPONSE: #{params}"
- end
+ def format_json_value(value)
+ formatted = JSON.pretty_generate(value)
+ formatted.length > 1200 ? "#{formatted[0...1200]}\n... <truncated>" : formatted
+ rescue JSON::GeneratorError, TypeError
+ value.inspect
+ end
- details = validation_result["details"]
- if details
- puts "VALIDATION DETAILS: #{details}"
+ def schema_for_json_value(value)
+ case value
+ when Hash
+ if value.empty?
+ { type: "object", additionalProperties: true }
else
- puts "POSSIBLE ISSUE W/: #{pointer}" if pointer.present?
+ {
+ type: "object",
+ additionalProperties: false,
+ properties: value.transform_values { |nested_value| schema_for_json_value(nested_value) },
+ required: value.keys,
+ }
end
+ when Array
+ item = value.compact.first
+ schema = { type: "array" }
+ schema[:items] = schema_for_json_value(item) if item
+ schema
+ when String
+ { type: "string" }
+ when Integer
+ { type: "integer" }
+ when Numeric
+ { type: "number" }
+ when TrueClass, FalseClass
+ { type: "boolean" }
+ when NilClass
+ { type: "null" }
+ else
+ {}
+ end
+ end
+
+ def json_pointer_leaf(pointer)
+ pointer.to_s.split("/").reject(&:empty?).last
+ end
+
+ def schema_validation_issue(validation_result)
+ pointer = validation_result["data_pointer"].presence || "root"
+
+ case validation_result["type"]
+ when "required"
+ missing_keys = validation_result.dig("details", "missing_keys") || []
+ "Missing required #{"property".pluralize(missing_keys.size)} #{missing_keys.join(", ")} at #{pointer}"
+ when "schema"
+ "Unexpected property at #{pointer}"
+ else
+ validation_result["error"] || "Schema mismatch at #{pointer}"
+ end
+ end
+
+ def schema_validation_suggested_fix(validation_result, params)
+ schema_pointer = validation_result["schema_pointer"].presence || "root schema"
+ data_pointer = validation_result["data_pointer"].presence
+ value = value_at_json_pointer(params, data_pointer)
+
+ case validation_result["type"]
+ when "required"
+ missing_keys = validation_result.dig("details", "missing_keys") || []
+ "Add #{missing_keys.join(", ")} to the response/request, or remove it from `required` at #{schema_pointer}."
+ when "schema"
+ property_name = json_pointer_leaf(data_pointer)
+ snippet = { property_name => schema_for_json_value(value) }
+ "If this response/request field is intentional, add this entry to the parent schema's `properties` object:\n#{format_json_value(snippet).indent(6)}\n If the field is always present, also add #{property_name.inspect} to the parent schema's `required` array."
+ when "array", "object", "string", "integer", "number", "boolean", "null"
+ "Update the payload to match the documented `type`, or replace the schema at #{schema_pointer} with:\n#{format_json_value(schema_for_json_value(value)).indent(6)}"
+ when "enum"
+ "Return one of the documented enum values, or add this value to the enum at #{schema_pointer}."
+ else
+ "Compare the value at the data path with the schema at #{schema_pointer}."
end
+ end
+
+ def format_schema_validation_result(validation_result, params, index)
+ pointer = validation_result["data_pointer"].presence
+ parent_pointer = pointer&.sub(%r{/[^/]+\z}, "")
+ lines = [
+ "#{index}. #{schema_validation_issue(validation_result)}",
+ " Error: #{validation_result["error"]}",
+ " Data path: #{pointer || "root"}",
+ " Schema path: #{validation_result["schema_pointer"].presence || "root"}",
+ " Value:",
+ format_json_value(value_at_json_pointer(params, pointer)).indent(5),
+ ]
+
+ if parent_pointer.present? && parent_pointer != pointer
+ lines.concat(
+ [
+ " Parent path: #{parent_pointer}",
+ " Parent value:",
+ format_json_value(value_at_json_pointer(params, parent_pointer)).indent(5),
+ ],
+ )
+ end
+
+ if validation_result["details"].present?
+ lines.concat([" Details:", format_json_value(validation_result["details"]).indent(5)])
+ end
+
+ lines.concat(
+ [" Suggested fix: #{schema_validation_suggested_fix(validation_result, params)}"],
+ )
+ lines.join("\n")
+ end
- expect(valid).to eq(true)
+ def schema_validation_failure_message(validation_results, params)
+ formatted_results =
+ validation_results
+ .map
+ .with_index(1) do |validation_result, index|
+ format_schema_validation_result(validation_result, params, index)
+ end
+
+ <<~MESSAGE
+ JSON schema validation failed with #{validation_results.size} #{"error".pluralize(validation_results.size)}:
+
+ #{formatted_results.join("\n\n")}
+ MESSAGE
+ end
+
+ def expect_schema_valid(schemer, params)
+ validation_results = schemer.validate(params).to_a
+ if validation_results.any?
+ raise RSpec::Expectations::ExpectationNotMetError,
+ schema_validation_failure_message(validation_results, params)
+ end
end
describe "response status" do