QTI utilities

This module provides utilities for creating and managing QTI 3.0 and 2.1 assessment packages, including generating IMS manifests and QTI test/item XML structures.

Building QTI assessments

By default, packages are created in QTI 3.0 format:

Example usage:

import { QtiTest, QtiItem, ImsPackage } from "@examplary/qti";

// Build a test with one question

const test = new QtiTest({
  identifier: "my-test",
  title: "My Test",
  language: "en",
});

const item = new QtiItem({
  identifier: "item-1",
  title: "Sample Question",
});

item.addResponseDeclaration({
  identifier: "RESPONSE",
  correctResponse: ["4"],
});

item.addItemBodyFromHtml("<p>What is 2 + 2?</p>");
item.addInteraction(
  new TextEntryInteraction({ responseIdentifier: "RESPONSE" }),
);

item.addResponseProcessing(ResponseProcessingTemplate.MatchCorrect);

item.addToTest(test);

// Create a package from the test

const pkg = new ImsPackage({
  identifier: "my-package",
  title: "My Package",
  language: "en",
});

item.addToPackage(pkg);
test.addToPackage(pkg);

// Get a ZIP of the package

const zip = await pkg.generateZip();

Creating QTI 2.1 packages

To create a QTI 2.1 package instead, specify the version when creating the package:

import { ImsPackage, QtiVersion } from "@examplary/qti";

const pkg = new ImsPackage({
  identifier: "my-package",
  title: "My Package",
  language: "en",
  version: QtiVersion.v2p1, // Creates a QTI 2.1 package
});

// Items and tests added to this package will automatically
// generate QTI 2.1 compliant XML
item.addToPackage(pkg);
test.addToPackage(pkg);

You can also generate XML in a specific version directly:

const qti21Xml = item.buildXml({ version: QtiVersion.v2p1 });
const qti30Xml = item.buildXml({ version: QtiVersion.v3p0 }); // default

Parsing QTI assessments

The library supports parsing both QTI 3.0 and 2.1 packages. The version is auto-detected:

import {
  QtiItem,
  ImsPackage,
  ImsManifestResourceType,
  QtiVersion,
} from "@examplary/qti";
import { readFile } from "fs/promises";

const contents = await readFile("./example-qti-package.zip");
const pkg = await ImsPackage.fromZip(contents);

// Check the detected version
console.log("Package version:", pkg.version); // QtiVersion.v3p0 or QtiVersion.v2p1

// Get item resources (works for both versions)
const itemResources = pkg.manifest.getResourcesOfType(
  pkg.version === QtiVersion.v2p1
    ? ImsManifestResourceType.imsqti_item_xmlv2p1
    : ImsManifestResourceType.imsqti_item_xmlv3p0,
);

for (const resource of itemResources) {
  const xml = await pkg.getResourceContentsString(resource.identifier);
  // fromXmlString auto-detects the version
  const item = QtiItem.fromXmlString(xml!);

  console.log("Question title:", item.title);
  console.log("Interactions:", item.getInteractions());
}