Skip to content

Commit 498ab06

Browse files
howard-ehoward-e
committed
Add docs on how aria-at-app and aria-at interact
1 parent 54a5375 commit 498ab06

File tree

2 files changed

+236
-2
lines changed

2 files changed

+236
-2
lines changed

‎docs/local-development.md‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@
66
- Version 14 or greater
77
- It is recommended to install node with [`nvm`](https://github.com/nvm-sh/nvm)
88
2. Yarn
9-
- Yarn is resposible for installing dependencies, similar to npm. This project is utilizing yarn workspaces to organize the code into a monorepo structure.
9+
- Yarn is responsible for installing dependencies, similar to npm. This project is utilizing yarn workspaces to organize the code into a monorepo structure.
1010
- For macOS, use: `brew install yarn`
1111
- For linux, See [yarn documentation](https://classic.yarnpkg.com/en/docs/install/#debian-stable)
1212

@@ -18,7 +18,8 @@
1818
```
1919
2. Set up local database using the instructions provided in [database.md](database.md).
2020
- Note: You must run `yarn db-import-tests:dev` after setting up your database to import the latest test harness into
21-
your project.
21+
your project. This imports the latest tests information from the [aria-at repository](https://github.com/w3c/aria-at).
22+
More information on how these repositories interact can be found in [the import-tests README](../server/scripts/import-tests/README.md).
2223
3. Run the server
2324
`yarn dev`
2425
Now you can navigate your browser to: [http://localhost:3000/](http://localhost:3000/). You need to use localhost instead of `0.0.0.0` because the cookie needs to be treated as secure.

‎server/scripts/import-tests/README.md‎

Lines changed: 233 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,233 @@
1+
# ARIA-AT Import Scripts Documentation
2+
3+
This directory contains scripts that handle the import of test plans and test data from the [W3C ARIA-AT repository](https://github.com/w3c/aria-at) into this application's database.
4+
5+
## Overview
6+
7+
The import process synchronizes test data from the external `w3c/aria-at` repository with the local database, creating `TestPlan` records, `TestPlanVersion` records, `Test` records, `Assertion` records and updating `At` records. The system supports both V1 and V2 test formats from the ARIA-AT repository.
8+
9+
## Architecture
10+
11+
### Main Entry Point
12+
13+
**`index.js`** - The primary entry point for the import script. It:
14+
15+
- Parses command-line arguments to db-import-tests (`-c` for specifying a commit). Usage can be viewed at [docs/database.md](../../../docs/database.md)
16+
- Orchestrates the cloning and import process
17+
- Handles cleanup of temporary files
18+
19+
### Core Components
20+
21+
#### 1. Git Operations (`gitOperations.js`)
22+
23+
Handles all interactions with the `w3c/aria-at` Git repository:
24+
25+
- **`cloneRepo(gitCloneDirectory)`** - Clones the ARIA-AT repository to a temporary directory
26+
- **`readCommit(directoryPath, commit)`** - Checks out a specific commit and retrieves git metadata (SHA, message, commit date)
27+
- **`readDirectoryGitInfo(directoryPath)`** - Reads git information for a specific directory to determine when test patterns were last modified
28+
29+
**Repository Details:**
30+
31+
- Repository URL: `https://github.com/w3c/aria-at.git`
32+
- Default branch: `master`
33+
34+
#### 2. Test Plan Version Operations (`testPlanVersionOperations.js`)
35+
36+
The core logic for processing and importing test data:
37+
38+
**Main Functions:**
39+
40+
- **`buildTestsAndCreateTestPlanVersions(commit, options)`** - Main orchestration function that:
41+
42+
- Checks out the specified commit (or default branch)
43+
- Runs `npm install` and `npm run build` in the cloned `w3c/aria-at` repository
44+
- Imports harness files and updates JSON resources
45+
- Recursively processes test directories
46+
- Creates test plan versions in the database
47+
- Handles cleanup operations
48+
49+
- **`processTestPlanVersion(options)`** - Processes a single test directory:
50+
51+
- Reads CSV metadata (`references.csv`, `assertions.csv`)
52+
- Parses test files from the built directory
53+
- Creates or updates `TestPlan` records
54+
- Creates `TestPlanVersion` records with associated tests
55+
- Deprecates older test plan versions
56+
- Creates assertion records
57+
58+
- **`importHarness()`** - Copies harness files from the ARIA-AT repository to the client and server resources directories
59+
60+
- **`updateJsons()`** - Processes and updates command and support JSON files:
61+
62+
- Extracts commands from `keys.mjs` ([V1 Test Format](https://github.com/w3c/aria-at/wiki/Test-Format-V1-Definition)) → `commandsV1.json`
63+
- Extracts commands from `commands.json` ([V2 Test Format](https://github.com/w3c/aria-at/wiki/Test-Format-Definition-V2)) → `commandsV2.json`
64+
- Extracts support data from [`aria-at/tests/support.json`](https://github.com/w3c/aria-at/blob/master/tests/support.json)
65+
66+
- **`updateAtsJson({ ats, supportAts })`** - Merges database AT records with support.json data and writes to `ats.json`
67+
68+
**Key Features:**
69+
70+
- **Pre-built Zip Support**: Some commits are stored as pre-built zip files in `./zips/` to avoid rebuilding. These are extracted to temporary directories during import. The process for creating those zips is described in [docs/local-development](../../../docs/local-development.md#adding-new-test-data-from-aria-at-repository)
71+
- **Recursive Directory Processing**: Automatically discovers test directories by looking for `references.csv` files
72+
- **Version String Generation**: Creates version strings in format `VYY.MM.DD` or `VYY.MM.DD-N` for duplicates
73+
- **Deprecation Logic**: Automatically deprecates older test plan versions when new ones are imported
74+
- **Hash-based Deduplication**: Uses test content hashing to avoid importing duplicate test plan versions
75+
76+
#### 3. Test Parser (`testParser.js`)
77+
78+
Parses test data from built `.collected.json` files and creates test objects:
79+
80+
**Format Support:**
81+
82+
- **[V1 Test Format](https://github.com/w3c/aria-at/wiki/Test-Format-V1-Definition)**: Legacy format where tests are grouped by test ID across all ATs
83+
- **[V2 Test Format](https://github.com/w3c/aria-at/wiki/Test-Format-Definition-V2)**: Current format where each AT has its own test instance
84+
85+
**Key Functions:**
86+
87+
- **`parseTests(options)`** - Main parsing function that:
88+
- Collects all `.collected.json` files from the built directory
89+
- Validates data consistency across collected files
90+
- Creates test objects using format-specific strategies
91+
- Generates test IDs, scenario IDs, and assertion IDs
92+
93+
**Test Object Structure:**
94+
95+
- Test ID (generated from test plan version ID and raw test ID)
96+
- Title and metadata
97+
- AT associations
98+
- Renderable content (test instructions, commands, assertions)
99+
- Rendered URLs (for test execution)
100+
- Scenarios (command sequences)
101+
- Assertions (with priorities, statements, phrases, exceptions)
102+
103+
#### 4. Settings (`settings.js`)
104+
105+
Configuration constants:
106+
107+
- `gitCloneDirectory` - Temporary directory for cloning the repository
108+
- `builtTestsDirectory` - Path to built tests in the cloned repo
109+
- `testsDirectory` - Path to source tests in the cloned repo
110+
- `PRE_BUILT_ZIP_COMMITS` - List of commits available as pre-built zips
111+
112+
#### 5. Types (`types.js`)
113+
114+
JSDoc definitions for:
115+
116+
- References
117+
- AT Settings
118+
- Assertions
119+
- Commands
120+
- Renderable Content
121+
- And other data structures used throughout the import process
122+
123+
#### 6. Utils (`utils.js`)
124+
125+
Utility functions:
126+
127+
- **`getAppUrl(directoryRelativePath, { gitSha, directoryPath })`** - Generates application URLs for test pages that proxy to the ARIA-AT repository
128+
129+
## Import Process Flow
130+
131+
1. **Initialization**
132+
133+
- Parse command-line arguments
134+
- Start database transaction to ensure atomicity
135+
136+
2. **Repository Setup**
137+
138+
- Clone `w3c/aria-at` repository to temporary directory
139+
- Check out specified commit (or default branch)
140+
- Retrieve git metadata (SHA, message, date)
141+
142+
3. **Build Process** (unless using pre-built zip)
143+
144+
- Run `npm install` in cloned repository
145+
- Run `npm run build` to generate test files
146+
- Import harness files to client/server resources
147+
- Update JSON files (commands, support, ATs)
148+
149+
4. **Test Discovery**
150+
151+
- Recursively scan test directories
152+
- Identify test directories by presence of `references.csv`
153+
- Determine test format version (V1 or V2) by checking for `assertions.csv`
154+
155+
5. **Test Processing** (for each test directory)
156+
157+
- Read metadata from CSV files
158+
- Parse `.collected.json` files from built directory
159+
- Generate test objects with proper IDs
160+
- Check for duplicate test plan versions (via hash)
161+
- Create or update `TestPlan` record
162+
- Deprecate older test plan versions
163+
- Create `TestPlanVersion` record
164+
- Create `Test` records (embedded in TestPlanVersion)
165+
- Create `Assertion` records
166+
167+
6. **Cleanup**
168+
- Run `npm run cleanup` in repository (if needed)
169+
- Remove temporary directories
170+
- Commit database transaction
171+
172+
## Usage
173+
174+
### Basic Usage
175+
176+
Import tests from the latest commit on the default branch:
177+
178+
```bash
179+
yarn db-import-tests:dev
180+
```
181+
182+
### Import Specific Commit
183+
184+
Import tests from a specific git commit:
185+
186+
```bash
187+
yarn db-import-tests:dev -c <commit-sha>
188+
```
189+
190+
### Import Multiple Commits
191+
192+
Import tests from multiple commits in sequence:
193+
194+
```bash
195+
yarn db-import-tests:dev -c "commit1 commit2 commit3"
196+
```
197+
198+
## Test Format Versions
199+
200+
### [V1 Test Format](https://github.com/w3c/aria-at/wiki/Test-Format-V1-Definition) (Legacy)
201+
202+
- Tests are grouped by test ID across all assistive technologies
203+
- Uses `keys.mjs` for command definitions
204+
- Single test object contains all AT variations
205+
206+
### [V2 Test Format](https://github.com/w3c/aria-at/wiki/Test-Format-Definition-V2) (Current)
207+
208+
- Each assistive technology has its own test instance
209+
- Uses `commands.json` for command definitions
210+
- Assertions include structured data:
211+
- `assertionStatement` - Full assertion text
212+
- `assertionPhrase` - Tokenized phrase per AT
213+
- `assertionExceptions` - Command-specific exceptions
214+
- Supports tokenized assertions per AT
215+
- Supports command-specific settings
216+
217+
## Database Schema Integration
218+
219+
The import process creates/updates the following database entities:
220+
221+
- **`TestPlan`** - Represents a test pattern (e.g., "alert", "button")
222+
- **`TestPlanVersion`** - A version of a test plan at a specific commit
223+
- **`Test`** - Individual test cases (embedded in TestPlanVersion JSON)
224+
- **`Assertion`** - Assertion records linked to tests
225+
- **`At`** - Assistive technology records (read from database, merged with support.json)
226+
227+
## Resource Synchronization
228+
229+
The import process synchronizes the following resources:
230+
231+
- **Harness files** - Copied from `resources/` to `client/resources/`
232+
- **Commands** - Extracted and written to `server/resources/commandsV1.json` and `server/resources/commandsV2.json`
233+
- **Support data** - Written to `server/resources/support.json` and `server/resources/ats.json`

0 commit comments

Comments
 (0)