search

pa11y / pa11y-ci

Pa11y CI is a CI-centric accessibility test runner, built using Pa11y
https://pa11y.org
GNU Lesser General Public License v3.0
515 stars 63 forks source link

Update README.md #173

Open ptmkenny opened 2 years ago

ptmkenny commented 2 years ago

The correct npm package for the HTML reporter is pa11y-ci-html-reporter, not pa11y-html-reporter. I found the documentation on reporters very confusing (see https://stackoverflow.com/questions/71145049/how-do-i-use-the-html-csv-reporters-in-pa11y-with-github-actions), so I rewrote it to be more clear. I also generally edited the document to be easier to understand.

hollsk commented 2 years ago

Thanks so much for doing this, @ptmkenny - your rewrites are great!

I guess my only concern with changing the name of the reporter in this documentation is that pa11y-ci-html-reporter wasn't written by the Pa11y team, it belongs to a Pa11y user. I'm a bit wary of linking to 3rd party packages in our documentation because it could give people the impression that we have control over and maintain them. It's not that I think @aarongoldenthal has secretly included a bitcoin miner in his package 🙃 more that we want people to have some clarity over whether a package actually originated from the Pa11y team in the first place so they know where to get support. But then if the HTML reporter that we do support doesn't work in Pa11y CI, it's not exactly useful for us to be directing people to install it in the documentation.

Any other Pa11y core folks want to chime in?

joeyciechanowicz commented 2 years ago

These are some lovely rewrites @ptmkenny .

wary of linking to 3rd party packages in our documentation

@hollsk totally agree. Though if the docs make it clear that this is not maintained by pa11y?

"Example of adding GitLabs npm module as a reporter:"

The big takeaway is definitely that the reporters are broken though 😱

aarongoldenthal commented 2 years ago

@hollsk @joeyciechanowicz I'll throw in my agreement for ensuring responsibilities are understood. There have been examples where issues were opened here for pa11y-ci-reporter-html (e.g. https://github.com/pa11y/pa11y-ci/issues/169). I do think there could be value in maybe linking to related projects, with an explanation of responsibility or lack thereof (e.g. I also publish pa11y-ci-reporter-cli-summary, which started as a test project for the reporter interface, and there are likely other related tools). I'm not sure if the right place is here, the pa11y.org website, or somewhere else (an Awesome Pa11y page?).

On the issues with pa11y reporters in pa11y-ci I took a look and captured the issue at https://github.com/pa11y/pa11y-ci/issues/174.

One other related thoughts on reporters... The published reporter modules are in a little bit of an intermediate place. The repositories here note that they're deprecate since they're integrated with pa11y, but the npm packages have not been officially deprecated, which might make it clearer. And including the pa11y-reporter-html in the example here may add to the confusion even once working (maybe update to link to the pa11y HTML reporter).

revolunet commented 7 months ago

Using npx, looks like the reporter is simply "html"

➜ npx pa11y https://google.fr --reporter=pa11y-reporter-html > out.html
Reporter "pa11y-reporter-html" could not be found

➜ npx pa11y https://google.fr --reporter=pa11y-ci-reporter-html > out.html
Reporter "pa11y-ci-reporter-html" could not be found

➜ npx pa11y https://google.fr --reporter=html > out.html
OK