pa11y-ci-reporter-runner 4.0.0 → 4.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (5) hide show
  1. package/LICENSE +1 -1
  2. package/README.md +69 -26
  3. package/lib/pa11yci-machine.js +10 -9
  4. package/lib/pa11yci-service.js +32 -13
  5. package/package.json +8 -8
package/LICENSE CHANGED
@@ -1,6 +1,6 @@
1
1
  The MIT License (MIT)
2
2
 
3
- Copyright (c) 2022 - 2023 Aaron Goldenthal
3
+ Copyright (c) 2022 - 2024 Aaron Goldenthal
4
4
 
5
5
  Permission is hereby granted, free of charge, to any person obtaining a copy
6
6
  of this software and associated documentation files (the "Software"), to deal
package/README.md CHANGED
@@ -1,10 +1,16 @@
1
1
  # Pa11y CI Reporter Runner
2
2
 
3
- Pa11y CI Reporter Runner is designed to facilitate testing of [Pa11y CI reporters](https://github.com/pa11y/pa11y-ci#write-a-custom-reporter). Given a Pa11y CI JSON results file and optional configuration it performs the Pa11y CI calls to the reporter, including proper transformation of results and configuration data. Functionally, it's an emulation of the Pa11y CI side of the reporter interface with explicit control over execution of each step.
3
+ Pa11y CI Reporter Runner facilitates testing of
4
+ [Pa11y CI reporters](https://github.com/pa11y/pa11y-ci#write-a-custom-reporter).
5
+ Given a Pa11y CI JSON results file and optional configuration it performs the
6
+ Pa11y CI calls to the reporter, including proper transformation of results and
7
+ configuration data. Functionally, it's an emulation of the Pa11y CI side of the
8
+ reporter interface with explicit control over execution of each step.
4
9
 
5
10
  ## Installation
6
11
 
7
- Install Pa11y CI Reporter Runner via [npm](https://www.npmjs.com/package/pa11y-ci-reporter-runner).
12
+ Install Pa11y CI Reporter Runner via
13
+ [npm](https://www.npmjs.com/package/pa11y-ci-reporter-runner).
8
14
 
9
15
  ```sh
10
16
  npm install pa11y-ci-reporter-runner
@@ -12,16 +18,22 @@ npm install pa11y-ci-reporter-runner
12
18
 
13
19
  ## Usage
14
20
 
15
- Pa11y CI Reporter Runner exports a factory function `createRunner` that creates a reporter runner. This function takes four arguments:
21
+ Pa11y CI Reporter Runner exports a factory function `createRunner` that creates
22
+ a reporter runner. This function takes four arguments:
16
23
 
17
24
  - `resultsFileName`: Path to a Pa11y CI JSON results file.
18
- - `reporterName`: Name of the reporter to execute. Can be an npm module (e.g. `pa11y-ci-reporter-html`) or a path to a reporter file.
19
- - `options`: Optional [reporter options](https://github.com/pa11y/pa11y-ci#reporter-options).
20
- - `config`: Optional Pa11y CI configuration file that produces the Pa11y CI JSON results.
25
+ - `reporterName`: Name of the reporter to execute. Can be an npm module, for
26
+ example `pa11y-ci-reporter-html`, or a path to a reporter file.
27
+ - `options`: Optional
28
+ [reporter options](https://github.com/pa11y/pa11y-ci#reporter-options).
29
+ - `config`: Optional Pa11y CI configuration file that produces the Pa11y CI
30
+ JSON results.
21
31
 
22
- ### Runner States
32
+ ### Runner states
23
33
 
24
- Pa11y CI Reporter Runner emulates calls from Pa11y CI to the given reporter for the given results file. There are five distinct states for the runner, as shown below:
34
+ Pa11y CI Reporter Runner emulates calls from Pa11y CI to the given reporter for
35
+ the given results file. There are five distinct states for the runner, as shown
36
+ below:
25
37
 
26
38
  ```mermaid
27
39
  %% It's unfortunate that mermaid charts don't render on npmjs.com,
@@ -35,36 +47,63 @@ flowchart LR;
35
47
  ```
36
48
 
37
49
  - `init`: The initial state of the runner.
38
- - `beforeAll`: In this state the runner calls the reporter `beforeAll` function.
39
- - `beginUrl`: In this state the runner calls the reporter `begin` function for a given URL.
40
- - `urlResults`: In this state the runner calls the reporter `results` or `error` function depending on the result for that URL. If there are subsequent URLs, the runner next moves to `beginUrl` for the next URL. If this is the last URL, the runner moves to `afterAll`.
50
+ - `beforeAll`: In this state the runner calls the reporter `beforeAll`
51
+ function.
52
+ - `beginUrl`: In this state the runner calls the reporter `begin` function for
53
+ a given URL.
54
+ - `urlResults`: In this state the runner calls the reporter `results` or
55
+ `error` function depending on the result for that URL. If there are
56
+ subsequent URLs, the runner next moves to `beginUrl` for the next URL. If
57
+ this is the last URL, the runner moves to `afterAll`.
41
58
  - `afterAll`: In this state the runner calls the reporter `afterAll` function.
42
59
 
43
- When calling reporter functions, the runner transforms the Pa11y CI results and configuration data to provide the appropriate arguments. For example, the `results` function is called with the results as returned from Pa11y (slightly different than those returned from Pa11y CI) and the consolidated configuration for the analysis of that URL.
60
+ When calling reporter functions, the runner transforms the Pa11y CI results and
61
+ configuration data to provide the appropriate arguments. For example, the
62
+ `results` function is called with the results as returned from Pa11y (slightly
63
+ different than those returned from Pa11y CI) and the consolidated configuration
64
+ for the analysis of that URL.
44
65
 
45
66
  The runner state can be obtained via the following runner functions:
46
67
 
47
68
  - `getCurrentState()`: The current state of the runner.
48
- - `getNextState()`: The next state of the runner (i.e. the state that will be obtained by calling the `runNext()` function).
69
+ - `getNextState()`: The next state of the runner (that is, the state that would
70
+ be obtained by calling the `runNext()` function).
49
71
 
50
72
  Both functions return an object with the following properties:
51
73
 
52
- - `state`: The current runner state (any state value shown above)
53
- - `url`: The current URL for any state with an applicable URL (`beginUrl` and `urlResults`), otherwise `undefined`.
74
+ - `state`: The current runner state (any state value shown previously)
75
+ - `url`: The current URL for any state with an applicable URL (`beginUrl` and
76
+ `urlResults`), otherwise `undefined`.
54
77
 
55
- ### Runner Execution
78
+ ### Runner execution
56
79
 
57
80
  The reporter runner has five control functions:
58
81
 
59
- - `runAll()`: Simulates Pa11y CI running the analysis from the provided JSON results file from the current state through the end, calling all associated reporter functions.
60
- - `runNext()`: Simulates Pa11y CI running through the next state from the provided JSON results file, calling the associated reporter function as noted above.
61
- - `runUntil(targetState, targetUrl)`: Simulates Pa11y CI running the analysis from the provided JSON results file from the current state through the specified state/URL, calling the associated reporter functions as noted above. An error will be thrown if the end of the results are reached and the target was not found. This function takes the following arguments:
62
- - `targetState`: The target state of the runner (any state above except `init`, or any valid value of the `RunnerStates` enum).
63
- - `targetUrl`: An optional target URL. If no URL is specified, the runner will stop at the first instance of the target state.
64
- - `runUntilNext(targetState, targetUrl)`: Provides the same functionality as `runUntil`, but execution ends at the state prior to the target state/URL, so that the target will execute if `runNext()` is subsequently called.
65
- - `reset()`: Resets the runner to the `init` state and re-initializes the reporter. This can be sent from any state.
66
-
67
- These command are all asynchronous and must be completed before another is sent, otherwise an error will be thrown. In addition, once a run has been completed and the runner is in the `afterAll` state it must be `reset` before accepting any run command.
82
+ - `runAll()`: Simulates Pa11y CI running the analysis from the provided JSON
83
+ results file from the current state through the end, calling all associated
84
+ reporter functions.
85
+ - `runNext()`: Simulates Pa11y CI running through the next state from the
86
+ provided JSON results file, calling the associated reporter function as noted
87
+ previously.
88
+ - `runUntil(targetState, targetUrl)`: Simulates Pa11y CI running the analysis
89
+ from the provided JSON results file from the current state through the
90
+ specified state/URL, calling the associated reporter functions as noted
91
+ above. An error is thrown if the end of the results are reached and the
92
+ target wasn't found. This function takes the following arguments:
93
+ - `targetState`: The target state of the runner (any state noted previously
94
+ except `init`, or any valid value of the `RunnerStates` enum).
95
+ - `targetUrl`: An optional target URL. If no URL is specified, the runner
96
+ stops at the first instance of the target state.
97
+ - `runUntilNext(targetState, targetUrl)`: Provides the same capability as
98
+ `runUntil`, but execution ends at the state prior to the target state/URL,
99
+ so that the target would execute if `runNext()` is subsequently called.
100
+ - `reset()`: Resets the runner to the `init` state and re-initializes the
101
+ reporter. This can be sent from any state.
102
+
103
+ These command are all asynchronous and must be completed before another is
104
+ sent, otherwise an error is thrown. In addition, once a run has been completed
105
+ and the runner is in the `afterAll` state it must be `reset` before accepting
106
+ any run command.
68
107
 
69
108
  ### Example
70
109
 
@@ -129,4 +168,8 @@ test('test reporter at urlResults state', async () => {
129
168
 
130
169
  ## Limitations
131
170
 
132
- When passing config to `results`, `error`, and `afterAll`, Pa11y CI Reporter Runner includes the same properties as Pa11y CI except the `browser` property (with the `puppeteer` `browser` object used by Pa11y CI). If the `browser` object is needed, testing should be done with Pa11y CI to ensure proper `browser` capabilities are available.
171
+ When passing config to `results`, `error`, and `afterAll`, Pa11y CI Reporter
172
+ Runner includes the same properties as Pa11y CI except the `browser` property
173
+ (with the `puppeteer` `browser` object used by Pa11y CI). If the `browser`
174
+ object is needed, testing should be done with Pa11y CI to ensure proper
175
+ `browser` capabilities are available.
package/lib/pa11yci-machine.js CHANGED
@@ -13,10 +13,10 @@ const { createMachine, assign } = require('xstate');
13
13
  */
14
14
  const pa11yciMachine = createMachine(
15
15
  {
16
- context: {
17
- urlIndex: 0,
18
- urls: []
19
- },
16
+ context: ({ input }) => ({
17
+ urlIndex: input.urlIndex,
18
+ urls: input.urls
19
+ }),
20
20
  id: 'pa11yci-runner',
21
21
  initial: 'init',
22
22
  // Opting in for v4, will be default in xstate v5
@@ -34,7 +34,7 @@ const pa11yciMachine = createMachine(
34
34
  beforeAll: {
35
35
  on: {
36
36
  NEXT: [
37
- { target: 'beginUrl', cond: 'hasUrls' },
37
+ { target: 'beginUrl', guard: 'hasUrls' },
38
38
  { target: 'afterAll' }
39
39
  ],
40
40
  RESET: { target: 'init' }
@@ -49,7 +49,7 @@ const pa11yciMachine = createMachine(
49
49
  urlResults: {
50
50
  on: {
51
51
  NEXT: [
52
- { target: 'afterAll', cond: 'isLastUrl' },
52
+ { target: 'afterAll', guard: 'isLastUrl' },
53
53
  { target: 'beginUrl', actions: 'incrementUrl' }
54
54
  ],
55
55
  RESET: { target: 'init' }
@@ -66,15 +66,16 @@ const pa11yciMachine = createMachine(
66
66
  {
67
67
  actions: {
68
68
  incrementUrl: assign({
69
- urlIndex: (context) => context.urlIndex + 1
69
+ urlIndex: ({ context }) => context.urlIndex + 1
70
70
  }),
71
71
  setInitialUrlIndex: assign({
72
72
  urlIndex: () => 0
73
73
  })
74
74
  },
75
75
  guards: {
76
- hasUrls: (context) => context.urls.length > 0,
77
- isLastUrl: (context) => context.urlIndex === context.urls.length - 1
76
+ hasUrls: ({ context }) => context.urls.length > 0,
77
+ isLastUrl: ({ context }) =>
78
+ context.urlIndex === context.urls.length - 1
78
79
  }
79
80
  }
80
81
  );
package/lib/pa11yci-service.js CHANGED
@@ -7,6 +7,7 @@
7
7
  * @module pa11yci-service
8
8
  */
9
9
 
10
+ const { createActor, getNextSnapshot } = require('xstate');
10
11
  const machine = require('./pa11yci-machine');
11
12
  const RunnerStates = require('./runner-states');
12
13
 
@@ -38,6 +39,14 @@ const StateTypes = Object.freeze({
38
39
  next: 'next'
39
40
  });
40
41
 
42
+ /**
43
+ * Generates a machine event object for the given event type.
44
+ *
45
+ * @param {string} eventType The type of event (a MachineEvents value).
46
+ * @returns {object} The machine event object.
47
+ */
48
+ const getMachineEvent = (eventType) => ({ type: eventType });
49
+
41
50
  /**
42
51
  * Gets the initial pa11yci-runner state machine context given an array of URLs.
43
52
  *
@@ -68,6 +77,7 @@ const hasUrl = (state) =>
68
77
  * @private
69
78
  */
70
79
  const getUrlForState = (machineState) =>
80
+ // Only a subset of states have an associated URL
71
81
  hasUrl(machineState.value)
72
82
  ? // User supplied input used to index user supplied data file
73
83
  // nosemgrep: eslint.detect-object-injection
@@ -126,12 +136,17 @@ const getStateSummary = (machineState) => ({
126
136
  const serviceFactory = (urls, actions) => {
127
137
  let pendingCommand;
128
138
 
129
- // Implement custom xstate interpreter, which allows for tracking for current
139
+ // Implement custom xstate actor, which allows for tracking for current
130
140
  // and the next state, which is required for some control functions.
131
- const pa11yMachine = machine.withContext(getInitialContext(urls));
132
- let currentState = pa11yMachine.initialState;
133
- // Machine.transition is a pure function, so only retrieves the state
134
- let nextState = machine.transition(currentState, MachineEvents.NEXT);
141
+ const pa11yActor = createActor(machine, {
142
+ input: getInitialContext(urls)
143
+ });
144
+ let currentState = pa11yActor.getSnapshot();
145
+ let nextState = getNextSnapshot(
146
+ machine,
147
+ currentState,
148
+ getMachineEvent(MachineEvents.NEXT)
149
+ );
135
150
 
136
151
  /**
137
152
  * Validates that a command is allowed in the given state. Throws if invalid.
@@ -167,24 +182,28 @@ const serviceFactory = (urls, actions) => {
167
182
  pendingCommand = true;
168
183
 
169
184
  // Send event to the machine and executes the action for the
170
- // current state (except in init, which has no action)
171
- currentState = machine.transition(currentState, event);
185
+ // new current state (except in init, which has no action).
186
+ currentState = getNextSnapshot(
187
+ machine,
188
+ currentState,
189
+ getMachineEvent(event)
190
+ );
172
191
  if (currentState.value !== 'init') {
173
- // Value is internal object state
192
+ // Value is internal object state.
174
193
  // nosemgrep: eslint.detect-object-injection, unsafe-dynamic-method
175
194
  await actions[currentState.value](getUrlForState(currentState));
176
195
  }
177
196
 
178
- // Check next state and save for reference (machine.transition
179
- // is a pure function, so only retrieves the state)
197
+ // Check next state and save for reference.
180
198
  if (currentState.value !== finalState) {
181
- nextState = machine.transition(
199
+ nextState = getNextSnapshot(
200
+ machine,
182
201
  currentState,
183
- MachineEvents.NEXT
202
+ getMachineEvent(MachineEvents.NEXT)
184
203
  );
185
204
  }
186
205
  } finally {
187
- // Ensure pending command is reset in all cases, including on error
206
+ // Ensure pending command is reset in all cases, including on error.
188
207
  pendingCommand = false;
189
208
  }
190
209
  };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "pa11y-ci-reporter-runner",
3
- "version": "4.0.0",
3
+ "version": "4.1.1",
4
4
  "description": "Pa11y CI Reporter Runner is designed to facilitate testing of Pa11y CI reporters. Given a Pa11y CI JSON results file and optional configuration it simulates the Pa11y CI calls to the reporter.",
5
5
  "main": "index.js",
6
6
  "scripts": {
@@ -41,18 +41,18 @@
41
41
  },
42
42
  "homepage": "https://gitlab.com/gitlab-ci-utils/pa11y-ci-reporter-runner",
43
43
  "devDependencies": {
44
- "@aarongoldenthal/eslint-config-standard": "^24.0.0",
45
- "eslint": "^8.52.0",
44
+ "@aarongoldenthal/eslint-config-standard": "^26.0.1",
45
+ "eslint": "^8.57.0",
46
46
  "jest": "^29.7.0",
47
47
  "jest-junit": "^16.0.0",
48
- "markdownlint-cli2": "^0.10.0",
48
+ "markdownlint-cli2": "^0.12.1",
49
49
  "pa11y-ci-reporter-cli-summary": "^3.0.0",
50
- "prettier": "^3.0.3",
51
- "tsd": "^0.29.0",
52
- "typescript": "^5.2.2"
50
+ "prettier": "^3.2.5",
51
+ "tsd": "^0.30.7",
52
+ "typescript": "^5.3.3"
53
53
  },
54
54
  "dependencies": {
55
55
  "lodash": "^4.17.21",
56
- "xstate": "^4.38.3"
56
+ "xstate": "^5.9.1"
57
57
  }
58
58
  }