Example in README crashes

[jrpool]

The Usage section of the README file contains the example:

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

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

Scraper.with(async (scraper) => {
  for (const input of await scraper.scrape("http://example.com")) {
    const outcomes = await Audit.of(input, rules).evaluate();
  }
});

But this script executed with Node.js crashes on Audit.of() with the error message

TypeError: iterable is not iterable
    at Object.reduce (/Users/c162712/Documents/repos/autotest/node_modules/@siteimprove/alfa-iterable/src/iterable.js:70:29)
    at fromIterable (/Users/c162712/Documents/repos/autotest/node_modules/@siteimprove/alfa-list/src/list.js:467:41)
    at Function.from (/Users/c162712/Documents/repos/autotest/node_modules/@siteimprove/alfa-list/src/list.js:454:16)
    at Function.of (/Users/c162712/Documents/repos/autotest/node_modules/@siteimprove/alfa-act/src/audit.js:19:50)
    at file:///Users/c162712/Documents/repos/autotest/tests/alfastd.mjs:12:34

I believe this is because rules is not iterable.

[Jym77]

Hi @jrpool, thanks for reporting. I'll look into it. I guess we haven't updated the readme at some point.

In the meantime, please have a look at the Alfa examples repository where you'll hopefully find inspiration on using Alfa 😃

[Jym77]

Hi @jrpool I've tried the code with no problem on my side.
I do suspect things happening around JS/TS handling of modules (and import statements) which seems to be a complex topic to say the least 😓

A possible issue is that this code is supposed to be TypeScript code that then needs to be built into JavaScript. When doing so (with a tsconfig.json similar to the main one in Alfa), I obtain the following JavaScript file:

"use strict";
Object.defineProperty(exports, "__esModule", { value: true });
const alfa_act_1 = require("@siteimprove/alfa-act");
const alfa_scraper_1 = require("@siteimprove/alfa-scraper");
const alfa_rules_1 = require("@siteimprove/alfa-rules");

alfa_scraper_1.Scraper.with(async (scraper) => {
    for (const input of await scraper.scrape("http://example.com")) {
        const outcomes = await alfa_act_1.Audit.of(input, alfa_rules_1.default).evaluate();
    }
});

which runs without problems (on Powershell on a windows box).
Does this code work on your side?

Another possible issue is Node version. Mine is v15.14.0. Our build scripts use Node v14 and 16, so I assume it should also work with these versions.

[jrpool]

Hi, @Jym77. Thank you for your helpful comment. I have tried your version under Node 14.16.0 and Node 16.8.0. In both cases, I do not get an error message. The outcomes variable has type 'object', as I expect. But the JSON stringification is an empty object. That is true not only for example.com, but also for a URL that has massive accessibility defects.

I have reviewed the examples, but they involve packages that I have not been using, and it is not evident that any of those packages is intrinsically required for use of alfa. That is why I have concentrated on the basic Node scripts in the README file.

[jrpool]

Some analysis suggests that the error message had been due to using rules instead of default as the second argument to Audit.of.

The following code outputs an audit object with _input and _rules properties. Both those properties have values that seem well-formed. The _oracle property of audit is a function with code () => alfa_future_1.Future.now(alfa_option_1.None).

But the script outputs an empty object as outcomes.

const {Audit} = require('@siteimprove/alfa-act');
const {Scraper} = require('@siteimprove/alfa-scraper');
const alfaRules = require('@siteimprove/alfa-rules');
Scraper.with(async scraper => {
  for (const input of await scraper.scrape('https://example.com/')) {
    const audit = Audit.of(input, alfaRules.default);
    console.log(`audit is\n${JSON.stringify(audit, null, 2)}`);
    const outcomes = await audit.evaluate();
    console.log(JSON.stringify(`outcomes has type ${typeof outcomes}`));
    console.log(JSON.stringify(`outcomes is ${JSON.stringify(outcomes, null, 2)}`));
  }
});

[Jym77]

Can you try the full scraping example (first run yarn build at top level of the examples repo, then run yarn test in the custom-testing/scraping directory).

It is essentially the same script as the one in the README.

---

When trying this version of your script:

const { Audit } = require("@siteimprove/alfa-act");
const { Scraper } = require("@siteimprove/alfa-scraper");
const alfaRules = require("@siteimprove/alfa-rules");
Scraper.with(async (scraper) => {
  for (const input of await scraper.scrape("https://example.com/")) {
    const audit = Audit.of(input, alfaRules.default);

    const outcomes = await audit.evaluate();
    const result = [...outcomes];

    console.log(`Found ${result.length} outcomes`);
    console.log(result[0].toJSON());
  }
});

I get

Found 100 outcomes
{
  outcome: 'passed',
  rule: {
    type: 'atomic',
    uri: 'https://alfa.siteimprove.com/rules/sia-r1',
    requirements: [ [Object], [Object], [Object] ],
    tags: [ [Object] ]
  },
  target: {
    type: 'document',
    children: [ [Object], [Object] ],
    style: [ [Object] ]
  },
  expectations: [ [ '1', [Object] ], [ '2', [Object] ] ]
}

I think the difference comes from the fact that outcomes is just a generator and that is likely not properly stringified.

[jrpool]

When I try to follow the instructions for the scraping example, I get an error on the command yarn npm login --scope siteimprove. The message says:

yarn run v1.22.17
error Command "npm" not found.

[jrpool]

Now I see that the toJSON() of the result of audit.evaluate() is not informative about the target, but the toJSON() of the _target property of that result is a rich description of the target. On that basis, it seems that I have what I need in order to use alfa.

[Jym77]

Concerning the login to Github packages, have you tried the workaround explained later in the readme? (also, this might be a yarn 2 command, as far as I understand yarn 1 and yarn 2 are fairly different)

---

Concerning the toJSON function, yes, they are serialisations which do not always provide "all" information because it is not clear what "all" would be (and it could be different for different persons). The children property in that JSON should contain the DOM tree below that <p> element (all the way down to the actual text) which can of course help.

But if you need to manipulate the elements themselves, you would likely prefer doing so on the object rather than their serialisation. Among other, the Element class has a path method to get the Xpath of the object. So, instead of outputting outcome.toJSON() you could output, for example, outcome.target.path(), depending on your need. The point is that the Alfa objects should be preferred to manipulate the data and the serialisation won't fit everybody's need.

(the EARL and SARIF serialisations (toEARL() and toSARIF()) seem to contain paths of DOM nodes, I am not sure why we chose to not include it in the JSON serialisation 🤔 I'll add it at some point, I guess it makes sense…)

[Jym77]

Does this tell me anything more than that some p element on the page failed the r73 rule? Naturally, one wants to know more.

Also, the expectations contains a Result<Diagnostic>, so it is either Ok or Err depending on whether the expectation passed or failed, and the diagnostic contains a least a message with a brief description (unfortunately, often nothing more 😕 )

[jrpool]

Thank you for these additional suggestions. They are helpful for accessing the available data.