Exams

An exam is a lesson learners take instead of read: a set of questions answered in one sitting, against the clock, graded once at the end. Passing it completes the lesson, so a course with an exam can't be finished, and its certificate can't be earned, without passing it. A course can have as many exams as you like, anywhere in its outline: a check at the end of a section, a final exam last.

Exams are the opposite of quizzes. A quiz is practice: answer as often as you like, every miss explains itself. An exam says nothing until it's graded, counts each attempt, and can limit attempts or make learners wait between them. Both use the same ```quiz fence, so a question you wrote for a lesson can move into an exam as is.

Adding an exam

In the course workspace, New exam at the foot of the outline (or ⌘K → "New exam in …") adds a lesson titled "Exam" at the end of the last section and opens it. Admin → Exams → New exam does the same from outside the course: pick the course, then Create exam (a course with no section yet gets one, "Lessons"). Rename it, and move it like any lesson: drag it in Edit outline, or pick its Section. An exam lesson shows a timer mark in the outline, for you and for learners.

A lesson is an exam or a lesson for good: no switch turns one into the other. Duplicating an exam makes another exam; a course or template copied from it keeps it an exam. Exams can't go in the Lesson Library.

Writing the exam

The exam's body is markdown, like a lesson's:

• Each ```quiz fence is one exam question. Its questions: entries are versions of that question: each attempt draws one of them at random. Write two or three versions of each question, so an answer list shared by one learner doesn't fit the next attempt.
• ## headings are sections. Before Start, learners see each section and how many questions it holds; the result shows a score per section ("Joins: 3 of 4") and names the weakest, so learners know what to study.
• Text above the first heading is the exam's introduction. Learners read it before Start, so it's the place to say what the exam checks and what to review first.
• Text between questions is shown as written: instructions, a schema to read, a scenario.

## Filtering

Every question uses the `orders` table: `id`, `customer_id`, `amount`.

```quiz
id: where-or-having
questions:                   # versions: each attempt draws one
  - id: v1
    ask: Which clause keeps customers whose orders total over €100?
    options:
      - text: "`HAVING SUM(amount) > 100`"
        correct: true
      - text: "`WHERE SUM(amount) > 100`"
  - id: v2
    ask: Which clause filters rows before they are grouped?
    options:
      - text: "`WHERE`"
        correct: true
      - text: "`HAVING`"
```

Every question type works: choice, choices, answer and order. Two quiz rules change in an exam: why is optional (nothing is explained during an exam), and see: is ignored (an exam doesn't send learners back to a lesson). The Question menu above the editor adds a question or a version, and inside a question ⌘⇧Enter adds the next version.

The problems list under the editor works like a lesson's. These block Publish:

• no question yet;
• a fence that doesn't parse, or settings out of range;
• a lab (exams hold questions only, for now);
• a second ```exam settings fence;
• more than 100 questions.

These are warnings: a question with only one version (every learner gets it word for word), placeholders left from a template, and the quiz item-writing rules.

The settings

Exam settings, above the editor, holds the rules:

A field takes effect when you leave it (or press Enter). The settings are written into the exam's body as an ```exam fence at the top, so they save, publish, show in history and roll back with the questions. You can also edit the fence by hand; the form follows it.

time_limit: 45  # minutes
pass_mark: 80  # % of the questions right
attempts: 3
retake_wait: 24  # hours after a failed attempt
shuffle_questions: true
days_to_pass: 30  # from the first lesson the learner opens in this course
reminders: [3, 1]  # emails, in days before the end

Under the settings, the editor counts what learners get: "12 questions", or "12 questions, 30 versions: an attempt draws one version of each question" once a question has more than one version. Two entries in one ```quiz fence are one question asked two ways; to ask both, give each its own fence: in the Question menu, pick New question…, then Add question.

Shuffle questions gives each attempt a fresh order within each section; the sections, and the text between questions, stay where you wrote them. Options are shuffled either way, unless a version says shuffle: false.

Publishing

An exam publishes like any lesson: Publish lesson, then Publish changes, Unpublish, and the course's Review & publish. The learner preview (Preview draft as learner) shows the rules and every version of every question, with its answer key.

Changes never disturb an attempt in progress or a result: an attempt keeps the questions it drew, its time limit and its pass mark. The attempts allowed and the wait before a retake are read as published now, so a change applies to everyone at once, including learners already waiting.

Unpublish hides the exam and stops new attempts. An attempt already running isn't cut short: its learner can keep answering and submit until its time runs out, and it's graded like any other.

What learners see

The exam is open to every signed-in learner who can open the course, wherever it sits in the outline: they can take it before finishing the lessons above it. Visitors see the rules and a Sign in to take the exam button, never the questions.

The exam's page states the rules ("20 questions in 30 minutes, 70% to pass, 3 attempts"), the exam's introduction, What it covers (each section and its number of questions), how it works and how many attempts are left, then Start the exam. Start asks once more ("Start now? You'll have 30 minutes, and the clock can't be paused."), so a curious click never costs an attempt.

• The exam takes the page. From Start until the result, the page shows only the exam: no academy header, no course outline, no breadcrumb, no links to the lessons before and after it, no Report a problem. They come back with the result.
• The questions are listed on the left, where the course outline was: a click jumps to the question, a ✓ marks each question whose answer is saved, and the question in view stands out. On a narrow screen the list is hidden; Next unanswered in the bar at the top does the same job everywhere.
• Flag for review on a question marks it in the list, as a reminder to come back. Flags stay with the browser, are never graded, and survive a reload; the next attempt starts without them.
• The clock is the server's. It starts on Start and doesn't stop. Reloading the page, switching devices or closing the tab doesn't pause it. Under 5 minutes the countdown turns amber and says so; under a minute it turns red.
• Every question is on one page, in the order you wrote them, or shuffled within each section if you asked for it. A question with more than one right answer says Select all that apply.
• Answers save as they're given, with nothing marked right or wrong. The bar at the top counts the answered questions. If the connection drops, the bar says an answer didn't save and keeps trying; Submit sends every answer not yet saved before it closes the attempt, and waits while one can't be saved, so no answer is lost to the connection.
• Submit asks for confirmation where it was pressed and names the questions still unanswered ("Questions 3 and 5 are unanswered and count as wrong") and the flagged ones; each number jumps to its question.
• At 0:00 the exam submits itself with the answers saved so far, and says so. If the tab was closed, the attempt is graded the same way as soon as the learner opens the exam again, or within an hour of the time running out if they don't. A pass completes the lesson then. If it was the last lesson left, the course's certificate follows, so a learner who closed the tab receives it within the hour.

The result shows Passed or Not passed, the score ("17 of 20 (85%) — 70% needed") and the score per section, never the right answers or which questions were wrong. An attempt the clock submitted says time ran out. A fail names the weakest section ("Weakest section: Joins, 1 of 4.") and says when the learner can try again, in their own time zone ("tomorrow at 3:42 PM"), or that they've used every attempt. Every graded attempt is listed under Your attempts.

Before a learner's last attempt, the page says "This is your last attempt."

When the exam has days to pass, the page also says when the exam closes for the learner.

An exam lesson has no Complete button: Pass the exam to complete this lesson stands in its place. A learner who passed has passed: later attempts aren't offered. A learner can start at most 10 exam attempts a day, across all your exams.

Days to pass

Days to pass gives each learner a set number of days to pass the exam, so a certification gets finished instead of drifting.

When the clock starts

A learner's clock starts the first time they open any lesson of the course. "Open" means a signed-in learner loads a lesson's page: the first lesson, a lesson in the middle, a lab, or the exam lesson itself. Whichever comes first starts it.

These don't start it:

• opening the course page (its description, outline and Start button), a learning path, a catalog or the academy's home;
• visitors who aren't signed in;
• your team's previews in the admin (Preview draft as learner).

From that moment the learner has exactly the number of days you set, to the minute: a clock started on November 5 at 3:42 PM with 30 days ends on December 5 at 3:42 PM. It runs whether the learner comes back or not, and nothing pauses it.

Each exam has its own clock. In a course with two exams with days to pass, the first lesson the learner opens starts both.

Learners already in the course when you add days to pass (or publish an exam with them) start their clock at the next lesson they open. Nobody's clock is backdated to an earlier visit, so nobody finds the exam closed on the day you publish it.

What learners see

The terms of the exam say it ("20 questions in 30 minutes, 70% to pass, 3 attempts, 30 days from the first lesson"), on the exam's page and on the Exams page. Under the terms, while the learner hasn't passed:

• Before their clock starts: "You have 30 days to pass this exam, counted from the first lesson you open in this course."
• While it runs: "This exam closes for you on December 5 at 3:42 PM.", in the learner's own time zone. From the exam's first reminder on (3 days before the end by default, the last day when it has none) the line turns amber.
• After it ends: "Your time to pass this exam ended on December 5, 2026." and "To try again, ask the academy for more time." There is no Start button.

The course page says the same in one line under its Start button: "Once you open a lesson, you have 30 days to pass the exam.", then when the exam closes, then that the time ended. A learner who passed sees none of these.

A failed attempt's wait can outlast the clock: a learner who fails a day before the end, with a 24-hour wait, can't try again in time. The page says so instead of naming a retake time.

The reminders

Reminders sets when a learner who hasn't passed gets an email about their end: up to two, each 1 to 7 days before it, like 3, 1. A new exam sends one, 3 days before. Leave the field blank for none: the date still shows on the course and exam pages.

Reminders stay close to the end on purpose. One sent weeks ahead reads as "plenty of time", and the first reminder does most of the work, so two is the most.

Each email says:

• how long is left, the exam and the course, and when it ends (in UTC);
• how many of the course's lessons they've completed, and the lesson to open next, linked: the one Continue opens on the course page;
• how long the exam takes, and how many attempts they have left;
• that after the end only your academy can give more time;
• a link to stop reminder emails from your academy.

It comes from your academy's name and goes out within the hour after its day begins. The last day's says hours ("24 hours left"): an email can't know the reader's time zone.

A reminder goes only when it can help:

• Not to a learner who passed or used every attempt (they can't start without you; give them another attempt and the next reminder goes), and not while they're taking the exam (it goes an hour later if they still need it).
• Never late. A reminder whose day passed without it is dropped, and the next one goes on its own day.
• Never twice for the same end.
• Only with time to spare. A reminder needs more days to pass than its own: with 3 days to pass, a 3-day reminder never goes (the editor warns), and a 1-day one does.
• Checked again right before sending. A learner who passed, started an attempt, got more time or stopped reminders since it was queued doesn't get it.

Send me a test, under the settings, emails you the first reminder with the exam's settings and the course's lessons. Its stop link opens a page that says it's a test.

Stopping reminders

The link at the bottom of each reminder opens a page with Stop reminder emails. Mail apps that show their own Unsubscribe button use the same stop. It stops every exam reminder from your academy for that learner, at every exam. It never stops sign-in, certificate or security emails, and the dates stay on the pages. The same page has Send them again.

A learner who marks any email from your academy as spam (a reminder or a certificate email) gets the same stop, as if they had pressed it.

A learner's page in Admin → Learners says when they stopped them, and under Time to pass lists each reminder for their current end: waiting to send, sent or delivered (and when), bounced, marked as spam, or not sent. Their Emails list has the rest of their mail.

When time runs out

Start stops working at the end, judged on the server's clock. An attempt already running isn't cut short: the learner can finish and submit it, and a pass counts.

The learner's page in Admin → Learners shows their Time to pass for each exam ("Until …" or "Ended …") and Out of time when it ran out. Give more time gives them the exam's days again, counted from the click, and the reminders again before the new end. The Exams page lists everyone out of time, with the same button. Every role can give more time.

A learner who used every attempt and also ran out of time reads Out of attempts. Give them an attempt and more time.

Changing the days

A learner's end date is set when their clock starts. Changing the number of days later applies to the clocks that start after you publish the change; it never moves a date a learner was already given. To give one learner more, use Give more time.

Reminders apply as published now: a change reaches every running clock from its next reminder.

Removing the days to pass (blank, then publish) frees everyone at once: no end, no reminder, no closed exam. Adding them back brings each learner's date back as it was, so a date that passed in between closes the exam for that learner until you give more time. Unpublishing and publishing the exam again works the same way.

Another attempt

A learner who has used every attempt sees "ask the academy for another attempt". Their page in Admin → Learners lists every exam they've taken or have a clock at, with their attempts ("3 of 3") and where they stand: Passed, Taking it now, Out of attempts, Out of time, Not passed yet or Not started. Give another attempt appears once they're out. Each click allows one more attempt ("3 of 4 (1 given)"), for that learner and that exam only. The Exams page lists everyone out of attempts at any exam, with the same button.

The Exams page

Admin → Exams lists every exam in your courses, in course order:

• Exam: its title (opening it in the editor) and course. Draft or Changed says the exam isn't published or has unpublished edits; Course not published says learners can't reach it yet.
• Terms: what learners get, from the published exam ("20 questions in 30 minutes, 70% to pass, 3 attempts"), and how many versions when a question has more than one. An unpublished exam shows its draft's.
• Learners: learners who started it at least once.
• Passed: learners with a passing attempt, and their share of those with a graded one.
• Passed first try: the share of learners with a graded attempt whose first graded attempt passed.
• Out of attempts: learners who used every attempt allowed, including any you gave, without passing. An exam with unlimited attempts never has any, nor does an unpublished one: learners can't take it, so its limit doesn't count until you publish it again.
• Out of time: learners whose days to pass ended without a pass, whether or not they ever started the exam. The column shows once an exam has days to pass.
• Attempts opens the course's Exam section in Course analytics, in the same account.

A running attempt counts toward Learners but waits for its grade, and so does one whose time ran out with the tab closed: it's graded within the hour. Your team's own attempts are left out.

Out of attempts, under the list, names each learner out of attempts at an exam in the list, newest attempt first: their attempts ("3 of 3", or "4 of 4 (1 given)"), their last attempt, and Give another attempt. Once given, the learner leaves the list until that attempt is used too.

Out of time, under it, names each learner whose days to pass ended, latest end first: their attempts, when their time ended, and Give more time.

Course narrows the list to one course. Attempts from counts only one account's learners, or Individuals (learners with no company), in the numbers and both lists; the list of exams stays the same. Courses without an exam opens New exam for the course you pick.

Certificates

An exam has no certificate of its own: it is part of its course. The course's certificate requires every lesson complete, and an exam lesson completes only by a pass. The certificate's record shows an Exam row for each exam passed: its rules ("20 questions in 30 minutes, 70% to pass") and when, never the score. Its Open Badges document lists the same pass as evidence.

Attempts in analytics

Every attempt is on the course's page in Course analytics, in its Exam section (Exams, with an Exam column, when the course has more than one), newest first: the learner (linking to their page), when they started, their score, and Passed, Not passed, In progress or Time up: the time ran out with the tab closed, and the attempt is graded within the hour with the answers it saved. Like every analytic, the list follows the page's account and period, and leaves your team out. The exam lesson is also a row of the lesson funnel. Exam questions never appear on the Quizzes page or in quiz analytics; the Exams page holds each exam's numbers across courses.

Webhooks

With an outbound webhook set, every graded attempt sends exam.graded (the score, by section, and whether it passed), and a learner who can't start the exam any more without you sends exam.closed: out of attempts, or out of time when their days to pass end. Point them at your CRM or email tool to follow up a near miss, or to reach someone out of time before they ask. A pass also completes the lesson, which sends lesson.completed.

In the content export

The content export writes an exam lesson like any lesson, its file holding the settings fence and the questions, and marks it kind: exam in course.yaml. A repo sync reads kind: exam too: it creates the lesson as an exam, and refuses to change an existing lesson's kind.

Not yet

• Hands-on tasks. Exams ask questions only. Hands-on proof stays the assessed certificate's job: every lab check passed against real state.
• Paid attempts. An attempt can't be sold yet.
• Learning path exams. An exam belongs to one course.
• Per-question analytics for an exam, and extra time for one learner.
• Proctoring. Not planned. Versions, shuffling, the clock and keys that never reach the browser make sharing answers hard; they don't watch the learner.