@falkenslab/moodle-driver 0.0.0-stage → 0.3.1

package/dist/areas/questions/banks.js

@@ -0,0 +1,239 @@
+// Question banks (Moodle 5: shared banks are qbank activities; quizzes keep private ones), their
+// questions read from the bank page by field names and icons, questions imported from a GIFT or
+// Moodle XML file through the import form, and single questions made through their edit form.
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { checkLocalFiles } from "../../core/files.js";
+import { formValue, openForm, setFields, submitForm, uploadToDraft } from "../../core/forms.js";
+import { NotLoggedInError, openSitePage } from "../../core/session.js";
+import { MoodleError } from "../../core/errors.js";
+/** The bank isn't there, or Moodle refused the questions. */
+export class QuestionBankError extends MoodleError {
+    name = "QuestionBankError";
+    constructor(message) {
+        super(message, "question-bank");
+    }
+}
+/** A course's question banks: its shared ones and the activities' own, as the banks page lists them. */
+export async function questionBanks(context, siteUrl, courseId) {
+    const page = await openSitePage(context, siteUrl, `question/banks.php?courseid=${courseId}`);
+    try {
+        if ((await page.locator("body#page-question-banks").count()) === 0) {
+            throw new QuestionBankError(`You can't see course ${courseId}'s question banks: the course doesn't exist, or you aren't allowed.`);
+        }
+        return await page.evaluate(() => {
+            const doc = globalThis.document;
+            return Array.from(doc.querySelectorAll(".question-banks-list li")).flatMap((item) => {
+                const link = item.querySelector('a[href*="/mod/"][href*="view.php"]');
+                const match = /\/mod\/([a-z0-9_]+)\/view\.php\?(?:.*&)?id=(\d+)/.exec(link?.getAttribute("href") ?? "");
+                if (!match)
+                    return [];
+                return [{ id: Number(match[2]), name: (link?.textContent ?? "").replace(/\s+/g, " ").trim(), type: match[1], shared: item.closest(".shared-banks") !== null }];
+            });
+        });
+    }
+    finally {
+        await page.close().catch(() => undefined);
+    }
+}
+/** The bank page's categories (its category filter's options) and its context id. */
+async function bankCategories(page) {
+    return page.evaluate(() => {
+        const doc = globalThis.document;
+        const categories = Array.from(doc.querySelectorAll('[data-filterregion="filtertypedata"] select[data-field-name="category"] option'))
+            .filter((option) => option.value !== "")
+            // Names come indented, with their question count: "   Default for X (6)".
+            .map((option) => ({ id: Number(option.value), name: (option.textContent ?? "").replace(/\s+/g, " ").replace(/\s*\(\d+\)$/, "").trim() }));
+        return { contextId: Number(doc.querySelector(".questionbankwindow[data-contextid]")?.getAttribute("data-contextid")), categories };
+    });
+}
+/** The questions on a bank page: id from their checkbox, type from their icon, name from the in-place editor. */
+export function readBankQuestions(page, categoryId) {
+    return page.evaluate((categoryId) => {
+        const doc = globalThis.document;
+        return Array.from(doc.querySelectorAll("#categoryquestions tbody tr")).flatMap((row) => {
+            const id = Number(/^q(\d+)$/.exec(row.querySelector('input[type="checkbox"][name^="q"]')?.getAttribute("name") ?? "")?.[1]);
+            if (!id)
+                return [];
+            const type = /\/qtype_([a-z0-9_]+)\//.exec(row.querySelector('[data-columnid*="question_type_column"] img')?.getAttribute("src") ?? "")?.[1] ?? "";
+            const name = row.querySelector('[data-itemtype="questionname"]')?.getAttribute("data-value") ?? "";
+            const status = row.querySelector('select[name="question_status_dropdown"]')?.value;
+            const version = (row.querySelector('[data-columnid*="version_number_column"]')?.textContent ?? "").trim();
+            return [{ id, name, type, ...(status ? { status } : {}), ...(version ? { version } : {}), categoryId }];
+        });
+    }, categoryId);
+}
+// Modules that keep questions (FEATURE_USES_QUESTIONS in Moodle 5): a shared bank, a quiz's own.
+const BANK_MODULES = new Set(["qbank", "quiz"]);
+const bankModules = new Map();
+/**
+ * Checks that a course module keeps questions before opening its bank: Moodle creates a bank's
+ * categories for any activity whose bank page is opened (confirmed empirically, 5.2). The module
+ * comes from its settings form, which changes nothing.
+ */
+async function checkBank(context, siteUrl, activityId) {
+    const key = `${siteUrl}|${activityId}`;
+    let module = bankModules.get(key);
+    if (!module) {
+        const page = await openSitePage(context, siteUrl, `course/modedit.php?update=${activityId}`);
+        try {
+            module = (await formValue(page, "modulename")) ?? "";
+        }
+        finally {
+            await page.close().catch(() => undefined);
+        }
+        if (module)
+            bankModules.set(key, module);
+    }
+    if (!BANK_MODULES.has(module)) {
+        throw new QuestionBankError(`Activity ${activityId} ${module ? `is a ${module}, which` : "doesn't exist, or you can't edit it, so it"} has no question bank. Take a bank's id from the course's question banks.`);
+    }
+}
+// A bank page shows this many questions at most; more than that in one category isn't read.
+const PER_PAGE = 1000;
+/** A bank's categories and every question in them, category by category. */
+export async function questions(context, siteUrl, activityId) {
+    await checkBank(context, siteUrl, activityId);
+    const page = await openSitePage(context, siteUrl, `question/edit.php?cmid=${activityId}`);
+    try {
+        if ((await page.locator("body#page-question-edit .questionbankwindow").count()) === 0) {
+            throw new QuestionBankError(`Activity ${activityId} has no question bank you can see. Take a bank's id from the course's question banks.`);
+        }
+        const { contextId, categories } = await bankCategories(page);
+        const found = [];
+        for (const category of categories) {
+            await page.goto(new URL(`question/edit.php?cmid=${activityId}&cat=${category.id},${contextId}&qperpage=${PER_PAGE}`, siteUrl).href, { waitUntil: "domcontentloaded" });
+            found.push(...(await readBankQuestions(page, category.id)));
+        }
+        return { categories, questions: found };
+    }
+    finally {
+        await page.close().catch(() => undefined);
+    }
+}
+/** The form's category option ("<id>,<context>") for a category id; the form's default without one. */
+async function categoryOption(page, categoryId) {
+    if (categoryId === undefined)
+        return undefined;
+    const values = await page.evaluate(() => Array.from(globalThis.document.querySelectorAll('form.mform select[name="category"] option')).map((o) => o.value));
+    const value = values.find((v) => v.split(",")[0] === String(categoryId));
+    if (!value)
+        throw new QuestionBankError(`The bank has no category ${categoryId}: take one from the bank's categories.`);
+    return value;
+}
+/** Moodle's messages on the page after a form or an import (problems first). */
+async function pageProblems(page) {
+    return page.evaluate(() => {
+        const doc = globalThis.document;
+        return Array.from(doc.querySelectorAll("#region-main .alert-danger, #region-main .notifyproblem, #region-main .errorbox, #region-main .alert-warning"))
+            .map((element) => {
+            // Without the close button, the error box's heading and its "more information" link.
+            const copy = element.cloneNode(true);
+            for (const extra of Array.from(copy.querySelectorAll("button, .visually-hidden, .errorcode, h2, h3, h4")))
+                extra.remove();
+            return (copy.textContent ?? "").replace(/\s+/g, " ").trim();
+        })
+            .filter(Boolean);
+    });
+}
+/**
+ * Imports questions into a bank from a GIFT or Moodle XML file (a local path) or text, through the
+ * bank's import form; returns the questions created. A file Moodle can't parse comes back as a
+ * `QuestionBankError` with its messages, and nothing is imported.
+ */
+export async function importQuestions(context, siteUrl, activityId, { format, file, text, categoryId }) {
+    if ((file === undefined) === (text === undefined))
+        throw new QuestionBankError("Give the questions as a file or as text, one of the two.");
+    if (file)
+        await checkLocalFiles([file]);
+    const before = new Set((await questions(context, siteUrl, activityId)).questions.map((q) => q.id));
+    // Text goes up as a file, as a person would upload one.
+    const dir = text !== undefined ? await mkdtemp(path.join(tmpdir(), "moodle-import-")) : undefined;
+    const upload = dir ? path.join(dir, format === "gift" ? "questions.txt" : "questions.xml") : file;
+    if (dir)
+        await writeFile(upload, text, "utf8");
+    const page = await openForm(context, siteUrl, `question/bank/importquestions/import.php?cmid=${activityId}`).catch((error) => {
+        if (error instanceof NotLoggedInError)
+            throw error;
+        throw new QuestionBankError(`Activity ${activityId} has no question bank you can import into.`);
+    });
+    try {
+        await uploadToDraft(page, (await formValue(page, "newfile")), [upload]);
+        const values = { format };
+        const category = await categoryOption(page, categoryId);
+        // The file's own categories would override the one chosen.
+        if (category)
+            Object.assign(values, { category, catfromfile: false, contextfromfile: false });
+        await setFields(page, values);
+        await submitForm(page, "submitbutton");
+        const problems = await pageProblems(page);
+        if (problems.length > 0)
+            throw new QuestionBankError(`Moodle didn't import the questions: ${problems.join(" ")}`);
+    }
+    finally {
+        await page.close().catch(() => undefined);
+        if (dir)
+            await rm(dir, { recursive: true, force: true });
+    }
+    const created = (await questions(context, siteUrl, activityId)).questions.filter((q) => !before.has(q.id));
+    return { changed: `Imported ${created.length} question${created.length === 1 ? "" : "s"} into bank ${activityId}.`, questions: created };
+}
+export const QUESTION_TYPES = ["multichoice", "truefalse", "shortanswer", "numerical", "essay"];
+/** The option of a fraction select nearest to `fraction` (Moodle offers 100%, 90%, 83.33%…). */
+async function nearestFraction(page, field, fraction) {
+    const options = await page.evaluate((field) => Array.from(globalThis.document.querySelectorAll(`select[name="${field}"] option`)).map((o) => o.value), field);
+    return options.reduce((best, value) => (Math.abs(Number(value) - fraction) < Math.abs(Number(best) - fraction) ? value : best), options[0] ?? "0.0");
+}
+/**
+ * Creates one question in a bank through its type's edit form; returns its id. Imports are the way
+ * for several; this is for one-offs.
+ */
+export async function createQuestion(context, siteUrl, activityId, input) {
+    if (!QUESTION_TYPES.includes(input.type))
+        throw new QuestionBankError(`Question type ${input.type} isn't one this creates (${QUESTION_TYPES.join(", ")}); import it as GIFT or Moodle XML instead.`);
+    const answers = input.answers ?? [];
+    if (["multichoice", "shortanswer", "numerical"].includes(input.type) && answers.length === 0)
+        throw new QuestionBankError(`A ${input.type} question needs answers.`);
+    if (input.type === "truefalse" && input.correct === undefined)
+        throw new QuestionBankError("A true/false question needs its right answer (correct).");
+    const { categories } = await questions(context, siteUrl, activityId);
+    // The bank lists its "Top" category first, which holds no questions: its default one comes next.
+    const category = input.categoryId ?? (categories[1] ?? categories[0])?.id;
+    const page = await openForm(context, siteUrl, `question/bank/editquestion/question.php?cmid=${activityId}&category=${category}&qtype=${input.type}`).catch((error) => {
+        if (error instanceof NotLoggedInError)
+            throw error;
+        throw new QuestionBankError(`Activity ${activityId} has no question bank you can add to, or category ${category} isn't in it.`);
+    });
+    try {
+        // The form comes with a few blank answers; "Blanks for more" adds three at a time.
+        for (let i = 0; i < 10 && answers.length > Number((await formValue(page, "noanswers")) ?? answers.length); i++) {
+            await Promise.all([page.waitForNavigation({ waitUntil: "domcontentloaded" }), page.click('form.mform [name="addanswers"]')]);
+        }
+        const values = { name: input.name, "questiontext[text]": input.text, ...(input.defaultMark !== undefined ? { defaultmark: input.defaultMark } : {}) };
+        const choice = await categoryOption(page, input.categoryId);
+        if (choice)
+            values.category = choice;
+        if (input.type === "truefalse")
+            values.correctanswer = input.correct ? 1 : 0;
+        if (input.type === "multichoice")
+            values.single = answers.filter((a) => a.fraction > 0).length > 1 ? 0 : 1;
+        for (const [i, answer] of answers.entries()) {
+            values[input.type === "multichoice" ? `answer[${i}][text]` : `answer[${i}]`] = answer.text;
+            values[`fraction[${i}]`] = await nearestFraction(page, `fraction[${i}]`, answer.fraction);
+            if (answer.feedback !== undefined)
+                values[`feedback[${i}][text]`] = answer.feedback;
+            if (answer.tolerance !== undefined)
+                values[`tolerance[${i}]`] = answer.tolerance;
+        }
+        await setFields(page, { ...values, ...input.fields });
+        await submitForm(page, "submitbutton");
+        // Moodle lands on the bank, naming the question it changed last.
+        const id = Number(new URL(page.url()).searchParams.get("lastchanged")) || undefined;
+        return { changed: `Created ${input.type} question${id ? ` ${id}` : ""} "${input.name}" in bank ${activityId}.`, questionId: id };
+    }
+    finally {
+        await page.close().catch(() => undefined);
+    }
+}
+//# sourceMappingURL=banks.js.map

package/dist/areas/questions/banks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"banks.js","sourceRoot":"","sources":["../../../src/areas/questions/banks.ts"],"names":[],"mappings":"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"}

package/dist/areas/quizzes/attempts.d.ts

@@ -0,0 +1,123 @@
+import type { BrowserContext, Page } from "playwright-core";
+import type { Trail } from "../../options.js";
+import { MoodleError } from "../../core/errors.js";
+/** The quiz or attempt isn't there, or the person can't do what was asked. */
+export declare class QuizError extends MoodleError {
+    name: string;
+    constructor(message: string);
+}
+/** A label and value as Moodle shows them (site language). */
+export interface Detail {
+    label: string;
+    value: string;
+}
+/** What the quiz's page says: its info lines, dates, the person's attempts, whether they can start one. */
+export interface QuizInfo {
+    intro: string;
+    info: string[];
+    dates: Detail[];
+    feedback?: string;
+    attempts: {
+        id: number;
+        inProgress: boolean;
+        details: Detail[];
+    }[];
+    canStart: boolean;
+    messages: string[];
+}
+/** One input of a question, by its form name, with its options and current value. */
+export interface QuestionField {
+    name: string;
+    kind: "choice" | "checkbox" | "text" | "select";
+    label?: string;
+    options?: {
+        value: string;
+        label: string;
+    }[];
+    value?: string;
+}
+/** A question as the attempt or review page shows it. */
+export interface Question {
+    slot: number;
+    page?: number;
+    number?: string;
+    type: string;
+    state: string;
+    mark?: string;
+    text: string;
+    images: string[];
+    fields: QuestionField[];
+    feedback?: string;
+    rightAnswer?: string;
+}
+export declare function readQuizView(page: Page): Promise<QuizInfo>;
+/** The questions on an attempt or review page, with their fields read from the form. */
+export declare function readQuestions(page: Page): Promise<Question[]>;
+/** The pages of an attempt, from its navigation: slot → page. */
+export declare function readNavigation(page: Page): Promise<Record<number, number>>;
+/** A quiz's page as the person sees it: its description and dates, the person's attempts with their summary, and whether they can start one. */
+export declare function quizInfo(context: BrowserContext, siteUrl: string, activityId: number): Promise<QuizInfo>;
+/** Starts an attempt, or continues the one in progress, as the quiz page's button does; returns its id. */
+export declare function startAttempt(context: BrowserContext, siteUrl: string, activityId: number): Promise<number>;
+/** Every question of an attempt, page by page, with the page each is on. */
+export declare function readAttempt(context: BrowserContext, siteUrl: string, attemptId: number): Promise<Question[]>;
+/**
+ * Saves answers page by page, as the attempt's "next" button does; `beforeSave` runs with each
+ * page's questions (the realistic trail's reading pause). Throws, saving nothing more, on a field
+ * a page doesn't have.
+ */
+export declare function saveAnswers(context: BrowserContext, siteUrl: string, attemptId: number, answers: {
+    slot: number;
+    responses: Record<string, string>;
+}[], beforeSave?: (questions: Question[]) => Promise<void>): Promise<void>;
+/** Submits the attempt for grading, as "Submit all and finish" does, without its confirm dialog. */
+export declare function finishAttempt(context: BrowserContext, siteUrl: string, attemptId: number): Promise<void>;
+/** A finished attempt's review, as far as the quiz's review options let the person see it. */
+export declare function readReview(context: BrowserContext, siteUrl: string, attemptId: number): Promise<{
+    summary: Detail[];
+    questions: Question[];
+}>;
+/** Starts an attempt, or continues the one in progress, and gives its questions. */
+export declare function startQuizAttempt(context: BrowserContext, siteUrl: string, activityId: number): Promise<{
+    changed: string;
+    attemptId: number;
+    questions: Question[];
+}>;
+/**
+ * Saves answers in an attempt in progress without finishing it, and gives its questions afterwards.
+ * With the realistic trail, it first takes the time a reader needs for the questions and their
+ * options (ADR-005), calling `onProgress` with the seconds elapsed and the total.
+ */
+export declare function answerQuizQuestions(context: BrowserContext, siteUrl: string, attemptId: number, answers: {
+    slot: number;
+    responses: Record<string, string>;
+}[], { trail, onProgress }?: {
+    trail?: Trail;
+    onProgress?: (elapsed: number, total: number) => void;
+}): Promise<{
+    changed: string;
+    attemptId: number;
+    questions: Question[];
+}>;
+/** Submits an attempt for grading, and gives its review when the quiz shows it. */
+export declare function finishQuizAttempt(context: BrowserContext, siteUrl: string, attemptId: number): Promise<{
+    changed: string;
+    attemptId: number;
+    finished: true;
+    review: {
+        summary: Detail[];
+        questions: Question[];
+    } | undefined;
+}>;
+/**
+ * Sets a user override on a quiz, through its override form: other opening and closing dates, a time
+ * limit in minutes, or a number of attempts (0 unlimited); what isn't given stays the quiz's.
+ */
+export declare function setQuizOverride(context: BrowserContext, siteUrl: string, activityId: number, userId: number, { open, close, timeLimitMinutes, attempts }: {
+    open?: Date;
+    close?: Date;
+    timeLimitMinutes?: number;
+    attempts?: number;
+}): Promise<{
+    changed: string;
+}>;