taleem-test

A deterministic, extensible test evaluation engine for structured assessments.

taleem-test is a pure evaluation kernel.
It does not handle UI, storage, timing, or networking.

It only:

• checks a single question
• checks a full test
• aggregates results
• supports pluggable question types

Philosophy

• Pure evaluation logic
• Stateless engine
• UI-agnostic
• Runtime-agnostic (browser or backend)
• Extensible question types
• Deterministic output

Security depends on where you run the engine, not the engine itself.

Supported Question Types (Core)

• mcq (single choice)
• multi (multi-select)
• numeric
• short (short text)
• match
• order

Installation

npm install taleem-test

(or local usage in monorepo)

Basic Usage

import { createTestEngine } from "taleem-test";

const engine = createTestEngine();

const question = {
  id: "q1",
  type: "mcq",
  marks: 2,
  data: {
    correct: "b"
  }
};

const answer = {
  questionId: "q1",
  value: "b"
};

const result = engine.checkAnswer(question, answer);

console.log(result);
/*
{
  questionId: "q1",
  correct: true,
  score: 2,
  maxScore: 2
}
*/

Evaluating a Full Test

const test = {
  id: "t1",
  questions: [question]
};

const answers = [
  { questionId: "q1", value: "b" }
];

const result = engine.checkTest(test, answers);

console.log(result);
/*
{
  testId: "t1",
  totalQuestions: 1,
  attempted: 1,
  correctCount: 1,
  totalScore: 2,
  maxScore: 2,
  percentage: 100,
  results: [...]
}
*/

Question Structure

All questions share a base structure:

{
  id: "q1",
  type: "mcq",
  marks: 2,
  data: { ... }
}

Each type defines its own data shape.

Extending with Custom Question Types

engine.registerType("custom", (question, answer) => {
  const isCorrect = someCheckLogic(question, answer);

  return {
    questionId: question.id,
    correct: isCorrect,
    score: isCorrect ? question.marks : 0,
    maxScore: question.marks
  };
});

Security Model

taleem-test does not enforce security.

• In practice mode → run in browser.
• In exam mode → run on backend.
• Backend should strip correct before sending to client.

Same engine. Different runtime.

What This Library Does NOT Do

• No UI rendering
• No timing enforcement
• No answer storage
• No authentication
• No network calls
• No persistence
• No session management

It is a pure evaluation kernel.

Testing

npm test

Fully unit-tested using Vitest.

License

MIT