Skip to main content

Development

How to work on the driver itself. The repository's CLAUDE.md and .minispec/ hold the conventions and the design.

Commands​

npm install
npm run typecheck
npm run lint
npm run test:docker   # every test, in Docker
npm run test:sandbox  # the regression suite against the Moodle sandbox
npm run build         # dist/, with declarations
npm run docs:install  # the documentation site's dependencies
npm run docs:start    # the site on localhost, live
npm run cli:generate  # the moodle command's table and reference, after an API change
npm run docs:check    # every program in the guides compiles against the code
npm run docs:build    # the site, as published

npm publish runs the typecheck, the lint, the examples' check and the tests in Docker first (prepublishOnly): nothing is published unless they pass, so Docker has to be running.

Tests run in Docker​

The tests launch real browsers against the fake Moodle, one file at a time. They run only in Docker (scripts/in-docker.mjs, Playwright's image), never on the developer's desktop, where they'd open windows. One file:

MSYS_NO_PATHCONV=1 node scripts/in-docker.mjs npx tsx --test test/areas/quizzes/attempts.test.ts

(MSYS_NO_PATHCONV=1 is for Git Bash on Windows.) The container keeps its own node_modules in a volume, reinstalled when the lock file changes.

A real Moodle​

The fake Moodle stands for what the driver reads, but only a real site confirms it. The Moodle sandbox (a sibling repository, ../moodle-sandbox) runs Moodle 5.2 in Docker with a demo course, teacher and students. When it's running, scripts/in-docker.mjs joins its network and forwards localhost:8080 inside the container, so a scratch script can call the driver against it headless, on profiles logged in once.

npm run test:sandbox is the regression suite against it: every exported function, as a student, a teacher and an admin.

npm run test:sandbox                                      # every file in test/sandbox/
npm run test:sandbox -- test/sandbox/forums.sandbox.ts    # some
  • The accounts are read from the sandbox when the suite starts (node manage.mjs info --json; MOODLE_SANDBOX_DIR points elsewhere) into a temporary folder only you can read, deleted at the end. No password is printed or stored. The accounts' browser profiles stay in ~/.moodle-driver-sandbox (one folder per checkout; MOODLE_SANDBOX_PROFILES moves it), so later runs don't log in again: they hold the sandbox's session cookies, nothing else.
  • Course 3 is the content course and is only read; the sandbox's own course (2) is never used. Writes happen on a scratch course each file creates ("Driver check …") and deletes, and each test removes what it made.
  • The sandbox runs Moodle's cron in a container of its own, every minute, so copies, backups and restores finish as on a real site.
  • Test names start with the function they exercise (courseStructure: …). At the end a summary lists, per function, passed, failed or skipped with its reason, and the full run fails when an exported function is in no test, or a skip gives no reason.

It runs on demand, when you want to know the driver still works on a real Moodle (after changing how an area reads Moodle, or Moodle's version): it takes hours, so it's part of no release and of no npm publish.

Conventions​

  • Everything in English: code, comments, docs, commit messages; the site's guides also have a Spanish translation (ADR-015).
  • A function takes the browser context and the site, then ids, then options; it returns plain data.
  • Every page a function reads is opened with openSitePage(); services go through callService().
  • Read Moodle by structure (ids, data attributes, field names, body ids, URLs), never by visible text.
  • Page code with helper functions goes through inPage().
  • Errors a program can act on get their own class, with messages in Moodle's terms.
  • The library never prints, reads no environment variables, and knows nothing of its consumers.
  • Every public function declares its data categories in src/categories.ts; a test enforces it.
  • Every function gets a doc comment: the API reference is generated from them.

Documentation​

This site lives in docs/ (Docusaurus). Guides are Markdown under docs/content/, one line per paragraph; the API reference is generated by TypeDoc from src/index.ts and src/testing/index.ts on every build. A change that a program using the driver would notice updates the guide that describes it in the same commit. The site is published to GitHub Pages on every push to main.