Using Alfa directly in a website/browser environment

[TobiasG95]

Dear Alfa developers,
first of all I want to say great work with the Alfa-framework! I think it is an great contribution to making the web more accessible. I am already successfully testing Code of mine using the Puppeteer approach, but I was wondering if it is possible to use Alfa as compiled Javascript in a website/browser environment directly without Puppeteer or similar headless browsers? For example to do something like:

const outcomes = await Audit.of(window.document, rules).evaluate();

From my understanding the Input of the Audit.of() has to be a Page-object and can't be the document DOM-Element itself correct? Is there an alfa-package that can maybe convert DOM-elements in a way that they can be audited?

I have been trying basic examples with for example the alfa-scraper and packages like Browserify to bundle the code. But these rely on e.g. Puppeteer which obviously didn't work in the browser directly (or shouldn't be necessary because the website data is already there).

Thank you for your help in advance!

[Jym77]

Hi @TobiasG95,
that is definitely possible, but I'm not 100% sure of how it's done 🙈

We do have a browser extension that run on all major browsers (incl Chrome and Safari) and does not launch puppeteer either… So it is definitely possible 😄

Quickly looking into it, it seems that the trick is to serialize window.document into a Document.JSON object that can be fed to Document.from (from the alfa-dom package).

I'll check whether we can open source that serialisation function…

[TobiasG95]

Hi @Jym77,
thanks for the quick response! It would be great if the Serialization function or information on how to implement it would be available. This would enable applications like this (only in JS not Typescript):

import { Audit } from "@siteimprove/alfa-act";

import rules from "@siteimprove/alfa-rules";

const input = serializeForAlfa(window.document); //or maybe only subsets

const outcomes = await Audit.of(input, rules).evaluate();

Let me know if I can help or if you have any questions!

[Jym77]

Checking further (this is part of the code I'm not really using 😅 ), it seems that alfa-dom/Native.fromNode should do the trick to turn the node into an Alfa JSON that can be fed to Node.from

Does

import { Native, Node } from "@siteimprove/alfa-dom"

const alfaDocument = Node.from(Native.fromNode(window.document))

work?
(this is essentially what is done in Puppeteer.toNode with an extra trick around the JSHandle)

[TobiasG95]

This looks very promising.

I tried compiling this simple code example in the "/scratches" folder:

import {Audit} from "@siteimprove/alfa-act";
import { Node, Native } from "@siteimprove/alfa-dom";
import rules from "@siteimprove/alfa-rules";

(async () => {
  const alfaDocument = Node.from(Native.fromNode(window.document));
  const outcomes = await Audit.of(alfaDocument, rules).evaluate();
})();

and got this error:

scratches/testSinglePage.ts:3:16 - error TS2305: Module '"@siteimprove/alfa-dom"' has no exported member 'Native'.

3 import { Node, Native } from "@siteimprove/alfa-dom";

I am using the current version of Alfa 0.50.0. I checked the packages/alfa-dom folder and I can see two "native.ts" files. The native.ts in "packages/alfa-dom/src" says @internal before the export. Is the Native member maybe not public and therefore can't be included using the import statement? Does this minimal code example compile for you?

Thanks for your help again!

[Jym77]

Ah, yes, it is not exported at the top-level since it was meant to be internal… Grabbing it from one level deeper works:

import { Audit } from "@siteimprove/alfa-act";
import { Device } from "@siteimprove/alfa-device";
import { Node } from "@siteimprove/alfa-dom";
import { Page } from "@siteimprove/alfa-web";
import { Request, Response } from "@siteimprove/alfa-http";
import rules from "@siteimprove/alfa-rules";

import * as dom from "@siteimprove/alfa-dom/native";

(async () => {
  const alfaDocument = Node.from(dom.Native.fromNode(window.document));
  const outcomes = await Audit.of(
    Page.of(Request.empty(), Response.empty(), alfaDocument, Device.standard()),
    rules
  ).evaluate();
})();

(at least, it builds…)
(also, need to build a full Page for Audit.of)

I'll try and provide a nicer interface at some point, but I'm afraid not in the near future 😕

[TobiasG95]

Thanks for the fast response and I can confirm this worked! For anybody else that wants to try this, I used Browserify to bundle the Js Code and was able to run the result on a website in Chrome.

A nicer interface would be nice, but for now i think this is good enough. I guess this is also only an edge case. But thanks again for your time and the quick solution. I think Alfa is a great project and I am looking forward to testing it more :-)

[Jym77]

Glad to hear it works 🎉
I think this is an interesting use case that I want to support; I've recorded #1258 to remember to work on it.
Happy hacking.