We're using Rocket Validator to check Elixir School for HTML and accessibility issues.
This document is a quick guide on how to use that service, for full documentation please refer to https://docs.rocketvalidator.com
RV is an automated web crawler that finds the internal web pages on a site from a starting URL, and checks each web page found using:
- W3C HTML Validator to check for HTML issues.
- Axe-core to check for accessibility issues.
Both checkers are free and open source, and can be used on individual URLs.
Rocket Validator is a web crawler and reporting tool that lets you automatically check thousands of URLs (or just a few) with a single click.
The current site for Beta Elixir School has 1,040 web pages. Imagine if you had to check each web page manually, both for HTML and accessibility issues. That's 2,080 checks needed!
RV lets us automate this site-wide checking and also schedule periodic checks to constantly monitor for new issues.
RV is a paid service but Elixir School contributors have a free Pro account to work on this site. If you're an Elixir School contributor you just need to sign up for a free account, and contact [email protected] to have your account upgraded to Pro.
Once you're logged in at RV, you can create a new report. You just need to enter a starting URL (https://beta.elixirschool.com), and click on Start validation.
Your site validation report will be created, and the crawler will find the internal web pages, and validate each one for HTML and accessibility issues.
On the generated report, you can browse the results per each page found, or go to the Common HTML issues or Common accessibility issues tabs to find the issues found on the site, grouped by the kind of issue. The reports give you details of the affected pages, and the affected elements within each page.
RV can validate any site that has public URLs, and that includes your local development server if you use something like ngrok to create a temporary public URL for your dev server.
Here's a guide with more info but in short here's what you do:
- Launch the phoenix app, like in
iex -S mix phx.server. - Launch ngrok telling it to expose port 4000 and give it a meaningful URL, like
ngrok http 4000 --subdomain elixirschool-joe. - This will create a temporary public URL https://elixirschool-joe.ngrok.io that you can use to validate your dev site on RV.
Just remember to change joe by your name or whatever other string you want, but keep elixirschool somewhere on the URL to make it easier working with muting rules.
There are some issues that we can decide not to fix, for example HTML markup that is not correct by current standards, but is required by a third party tool, so it's out of our scope. Muting rules in RV lets us hide these issues on the reports. You can read the muting guide to see how it works, but basically a muting rule needs:
- A string to match URLs. It can be a whole URL if you want to be specific, or just a substring like
elixirschool, which is recommended as it will match both on the beta, staging and production sites, as well as your ngrok instances if you include that on the name. - A string to match the issue message. A substring is enough, for example matching on
Attribute “phx-will hide all issues regarding about invalid attributes set by Phoenix.
Each RV user defines their own muting rules, here are the rules that we've agreed to mute.
RV generates daily domain stats based on the reports you run, which can be shared by RV users. We're using the ones shared from @jaimeiniesta's account as a central reference:
Latest Stats and Reports for Beta Elixir School
Reports can be run automatically a schedule. For example in @jaimeniesta's account there's a weekly schedule to run a full report every Monday.
Reports can also be triggered automatically after a server deploy. This can be useful in staging deploys for example.