Documentation: Extend html-formatter and CustomRendering

[sashokbg]

Documentation request:

Please add some examples on how to implement our own html-formatter based on the existing one.
It is difficult to understand how to properly use the "CustomRendering" to change the way different parts are rendered.

Describe the solution you'd like
A complete step-by-step guide that explains how to extend the html-formatter and how to override different elements' rendering.

Thank you for your help.

[aurelien-reeves]

Did you had the opportunity to study the "react" component?

https://github.com/cucumber/common/tree/main/react/javascript

The HTML formatter is based on it. You may find more documentation, beginning with the README: https://github.com/cucumber/common/tree/main/react/javascript#cucumber-react

The HTML formatter javascript project is reponsible for building some html, css and javascript files using the "react" component. Then those html, css and javascript files are copied within other implementation - ruby and java - and used as templates.

In which language do you want to write your custom formatter?

[zbirizdo]

I would like to see some examples too please!

Should I write my own version of CucumberHtmlStream and somehow inject a CucumberReact component there so I can set the suggested customRendering attribute? I found this in cucumber/react-components:

<CucumberReact customRendering={{
  DocString: (props) => (
    <>
      <p>I am going to render this doc string in a textarea:</p>
      <textarea>{props.docString.content}</textarea>
    </>
  )
}}>
  <GherkinDocument />
</CucumberReact>

I am not a react developer and I don't really know what to do with this information (especially how is this going to get into my report).

Any help?

(by the way @aurelien-reeves your links are pointing to nowhere now)

[davidjgoss]

Hey @sashokbg @zbirizdo, sorry for the late reply.

To give a little background, the motivation for making the components customisable was to layer on some extra functionality in the Reports service https://reports.cucumber.io/. We wanted to do this with a nice pattern that would potentially be useful to other consumers, but I’d say it’s somewhat incomplete - as you’ve noted, currently you’d need to essentially reimplement the html-formatter module to make use.

Would you mind elaborating a bit in the use cases you have and how you want to change/extend the output? Depending on what they are we may be able to support them in other ways eg configurability.

[zbirizdo]

Hi @davidjgoss, sorry for the late reply on my part too. I managed to solve my problem with a somewhat different approach.

About my problem... I am doing visual regression tests and I was able to insert multiple images into my report (so I can compare the reference image of the test with the current screenshot and the one containing the differences). It is really a pain in the a** to keep the reference images up to date manually so my idea was to further extend the report with an "Approve" button so I can just click through the changes.

In the end I realized that I can write a custom formatter based on the built in html formatter to generate the report as it is now, then tap into the finished method to insert some js into the report's html file. With that js I can manipulate the dom to make my changes without diving into react too deep or rewriting anything.

It is not a nice solution and I wouldn't recommend doing this with more complex functionality, but for just an extra button I'm fine with it.