LmsIQ

Moodle regression testing, done with intent.

LmsIQ is a semantic automation platform for standard Moodle workflows. It lets teams validate that core Moodle behaviour — course management, user enrolment, activity completion, SCORM, quizzes, assignments — still works correctly after upgrades, theme changes, or configuration updates.

Workflows are written in plain YAML using Moodle-native verbs (openCourse, completeScorm, verifyActivityCompleted), not raw browser selectors. The Playwright layer is an implementation detail; your regression suite reads like a Moodle task list.

Quick start (global install)

# Step 1 — Install LmsIQ from npm
npm install -g lmsiq

# Step 2 — Install Playwright browser (run once per machine)
# LmsIQ bundles @playwright/test; you only need the Chromium binary.
npx playwright install chromium

# Step 3 — Create a project folder for your Moodle tests
mkdir my-moodle-tests
cd my-moodle-tests

# Step 4 — Init (creates .env + copies bundled core workflows)
lmsiq init

# Step 5 — Edit .env with your Moodle URL and test account credentials

# Step 6 — Verify setup (8 checks: env, URL, version, browser, logins, course, activities)
lmsiq doctor

# Step 7 — Run your first workflow
lmsiq run --workflow tests/workflows/core/auth/student-login.yaml

Install order: install lmsiq first, then run npx playwright install chromium. If you see a Playwright warning about missing dependencies during lmsiq run, Chromium may still install successfully — run npx playwright install chromium once to clear it.

Quick start (development — from this repo)

npm install
cp templates/.env.example .env
# edit .env, then:
npm run lmsiq -- doctor
npm run lmsiq -- run --workflow tests/workflows/core/auth/student-login.yaml

For a global lmsiq command while developing:

npm link
lmsiq init

Example workflow

id: student-scorm
name: Student completes SCORM activity

steps:
  - action: loginAs
    role: student

  - action: openCourse
    course: "${MOODLE_SCORM_COURSE_NAME}"

  - action: completeScorm
    activity: "${MOODLE_SCORM_ACTIVITY_NAME}"

  - action: verifyActivityCompleted
    activity: "${MOODLE_SCORM_ACTIVITY_NAME}"

  - action: logout

Core action catalog (Phase 1)

| Domain | Actions | |--------|---------| | Auth | loginAs, logout, verifyLoggedIn | | Courses | openCourse, createCourse, verifyCourseVisible | | Users | createUser, enrolUser, verifyUserEnrolled | | Activities | openActivity, createPage, createAssignment, createQuiz, createScorm | | Completion | completePage, completeScorm, submitAssignment, attemptQuiz, verifyActivityCompleted | | Admin | createCategory |

Recording assistant

Speed up workflow discovery on any Moodle site:

npm run lmsiq -- record --name my-workflow

LmsIQ opens a headed browser, watches your navigation, and writes a draft YAML when you press Enter. The draft uses Core semantic steps — always review before committing.

Custom workflows

Custom or organisation-specific workflows (proprietary plugins, custom dashboards, tenant navigation) belong in tests/workflows/company/ and are built on top of Core actions. See Company validation suite for examples.

Documentation

| Doc | Purpose | |-----|---------| | Product architecture | Core vs Custom layer boundary, Phase 1 scope, strategic rationale | | Moodle semantic actions | Action design principles, code layout, activity priority tiers | | Writing workflows | YAML contract, .env variables, supported actions, runner output | | Company validation suite | Customised Moodle smoke suite example |

Requirements

• Node.js 18+
• Playwright Chromium (npx playwright install chromium — once per machine)
• A running Moodle 5.x instance (doctor validates version and connectivity)