apiaryio / gavel2html Goto Github PK

Consider diffing the following:

Expected

[
  {
    "id": 1,
    "title": "Jogging in park"
  },
  {
    "id": 2,
    "title": "Pick-up posters from post-office"
  }
]

Actual

The proxy server could not handle the request, because upstream API server is unknown (missing HOST section in API Blueprint). You can try using Mock server instead: http://mock-faf90individualprivatetest.apiary-mock.com/notes

See the distorted diff when viewing the Responsive diff in the console.

This library should get rewritten from scratch.

• Version 0.2.0-unstable.1 used by apiary.io works, but isn't in git, we do not have it's CoffeeScript code anywhere, npm contains only compiled JS.
• Current version from git has regression bugs, algorithm to render JSON is changed for some reason and it doesn't work correctly.
• The library is unmaintainable, the code is undercommented and there are no docs (not even about the public interface)
• The behavior isn't specified, there are very little tests, mostly some regressions

Update: The gavel2html branch for 0.2.0-unstable.1, which is used by apiary.io, has been recovered from @kuba-kubula's backup disk. It is now pushed to GitHub under kubula/customize_json_converter_html branch name.

What

Consider I have the next specification toward my response body:

{
  "username": "admin",
  "notExistingProp": true
}

When the actual response body is:

{
  "username": "admin",
  "extraPropA": "...",
  "extraPropB": "..."
}

I see both extraPropA and extraPropB as new added properties, but I don't see the notExistingProp as red missing property.

Why

Perhaps a logic flaw during the analyzis if a property is missing:

Sometimes gavel2html fails to render the diff for some reason. We're able to see this when using gavel2html internally in apiary.io, but we don't know (yet) what's the exact input to trigger this.

gavelhtml: Internal error. 
 [TypeError: Cannot convert undefined or null to object 
  at Function.keys (<anonymous>:null:null) 
  at HeadersResultConverter._getLines (/app/node_modules/gavel2html/lib/headers-result-converter.js:27:37) 
  at HeadersResultConverter.getHtmlPrivate (/app/node_modules/gavel2html/lib/headers-result-converter.js:71:18) 
  at HeadersResultConverter.Converter.getHtml (/app/node_modules/gavel2html/lib/converter.js:46:17) 
  at Gavel2Html.getHtml (/app/node_modules/gavel2html/lib/gavel2html.js:61:26) 
  ...
]

Scenario

Whenever a body field is valid, even if an actual field has additional properties, those properties are not highlighted as added.

{
  "expected": { "login": "admin" },
  "actual": { "login": "joe", "newProp": true }
}

The newProp property won't be shown as the added one (green).

Expected behavior

Any property that is present in the actual HTTP message field (i.e. body, headers), but is not specified in the expected HTTP message field must be highlighted as the added one.

The README just isn't enough. I'm failing to understand how the library works. Issues:

• The library works also without Gavel (see #4). Why? What are benefits of it? How does it differ from other diff libraries out in the wild then?
• If the library works also without Gavel, what are the benefits of actually passing the Gavel output then? How does the gavel2html behave? Can I pass both data* and gavelResult options? What would be the output?
• What the usePointers means? Current description is completely cryptic.
• What structure should gavelResult have?
• What do following options mean and what is their behavior?
  • wrapWith
  • startTag
  • endTag
  • missingStartTag
  • addedStartTag
  • changedStartTag
  • comments
  • commentStartTag
  • commentEndTag
  • identString
• What is exactly the output of this library? What characteristics it should possess?

I would love to add the information, but unfortunately I'm not able to do so, because I don't understand the library myself. I would appreciate if @netmilk @kuba-kubula (as authors) or @XVincentX (as a recent user) could answer at least some of the questions. Feel free to add them as comment here, I'll gladly compile a nice README out of it later.

Actually this library is able to provide an output without gavel validation. Just matter of passing the right parameters. We should probably clarify what's going on here.

Related to apiaryio/dredd#705.