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.rbindex 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|endend- 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)+ endenddescribe "response status" do