Installation instruction ambiguities

[jrpool]

The README file seems to be ambiguous with respect to:

1. Whether building the auditor is a prerequisite to all modes of use.
2. What Grunt installation steps are required before grunt build. Apparently local installation of Grunt and creation of a Gruntfile are required, but this is not stated, nor is the content of the necessery Gruntfile specified.
3. Whether the puppeteer script could be adapted to use playwright.
4. How the output from HTMLCS_RUNNER.run() can be captured for further processing in either the puppeteer or the jsdom case.

[guygastineau]

    How the output from HTMLCS_RUNNER.run() can be captured for further processing in either the puppeteer or the jsdom case.

That is currently my issue. I am using the script with both marionette and webdriver (using geckodriver). It runs, but I get null as the return value. Is it printing it to the console or something?

I discovered this script is what pa11y uses to scan for accessibility. Maybe I can figure out how they are getting the information out of it.

[guygastineau]

I found the code in Contrib/PhantomJS/runner.js. It is indeed printing the results to the console separated simply with vertical bars |. The HTMLCS_Run.js file in the same directory has a function that suggests it returns JSON, but I don't know how to use that. The HTMLCS_RUNNER.run function says it takes a callback, but it doesn't use it. I was hoping I could just pass some callback to turn it all into JSON or something. Anyway, it looks like I'll have to patch it, since I don't find tricks for capturing the console output suitable for my needs.

[jrpool]

Testaro (https://www.npmjs.com/package/testaro) runs HTMLCS (and other packages). Testaro captures the output of HTMLCS and integrates it into its own output. The code and README file of Testaro show how it does that.

[guygastineau]

@jrpool thank you for the link. Hopefully, I didn't take this issue too far off topic.

I wrote a new runner locally that actually returns a value, but then I realized the machinery at the heart of HTMLCS is like continuation passing style but without return values. I started adding returns to the final expressions in all branches, but then work was over and I started drinking to cope with having to walk the graph manually.

I noticed many functions return false under some failure conditions, but otherwise they implicitly return null. I just want to get return values from the callbacks threaded through HTMLCS. Do you think a PR adding this while preserving backwards compatibility would be welcome? I'm sure I'm off topic now.