Giter Club home page Giter Club logo

gavel2html's Introduction

gavel2html

npm version Dependency Status devDependency Status Known Vulnerabilities

A utility library to render an HTML diff from the Gavel.js validation results.

Installation

npm install gavel2html

Usage

const gavel = require('gavel');
const Gavel2Html = require('gavel2html');

// Validate expected/actual HTTP transaction with Gavel.
const gavelResult = gavel(expected, actual);

const renderer = new Gavel2Html({
  // Pass the name of the field you wish to render
  fieldName: 'body',
  // ...and the validation result for that field
  fieldResult: gavelResult.fields.body,
});

const html = renderer.getHtml({
  wrapWith: '##data',
  startTag: '<span>',
  endTag: '</span>',
  missingStartTag: '<span class="missing">',
  addedStartTag: '<span class="added">',
  changedStartTag: '<span class="changed">',
  comments: true,
  commentStartTag: '<span class="comments">',
  commentEndTag: '</span>',
  identString: '  '
});

console.log(html);
<span>{&quot;name&quot;: &quot;hell</span><span class="missing">o</span><span>&quot;}</span>

API

Gavel2Html(options)

Creates a renderer instance with the given options.

Options

{
  // Gavel validation results field name.
  // Affects the converter being used internally.
  fieldName: 'statusCode' | 'headers' | 'body'

  // Gavel validation results for the given `fieldName`.
  // Refer to the Gavel's documentation for more details.
  fieldResults: GavelFieldValidationResults

  // Use JSON pointers from the Gavel validation results
  // passed in the `fieldResults` option.
  usePointers?: boolean
}

getHtml(options): string

Returns an HTML string representing the markup of the validation results data diff.

Options

{
  // String to wrap the outpout data with.
  // The "##data" acts as a placeholder that gets
  // substituted with the output results.
  // Example: <div>##data</div>.
  wrapWith?: string = '##data'
  startTag?: string = '<li>'
  endTag?: string = '</li>'
  jsonKeyStartTag?: string = ''
  jsonKeyEndTag?: string = ''

  // String to use at the beginning of
  // a missing sequence of characters.
  missingStartTag?: string

  // String to use at the beginning of
  // an added sequence of characters.
  addedStartTag?: string

  // String to use as a start when marking
  // a changed sequence of characters.
  changedStartTag?: string

  // Include comments in the output.
  comments?: boolean
  commentStartTag?: string
  commentEndTag?: string

  // String to use as a one level of indentation.
  identString?: string = '  '
}

gavel2html's People

Contributors

artem-zakharchenko avatar honzajavorek avatar kuba-kubula avatar kylef avatar miiila avatar pksunkara avatar

Watchers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

gavel2html's Issues

Architecture

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.

There is no documentation

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.

Missing required property is not present in the diff

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:

if errorPointer? # filter out non json related errors
if @areArraysIdentical pathArrayTransformed, jsonPointer.parse(errorPointer)
# key is missing in real and is present in expected, so it's missing
if errorPointer not in @dataRealPointers[compiledPointersKey]
if message
message = ' | ' + message
message = error['message'] + message
state = -1

gavel is not required

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.

Diff between expected JSON and actual text is malformed

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.

TypeError: Cannot convert undefined or null to object

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) 
  ...
]

Valid body doesn't get diff of added properties

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.

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.