Files
coursebank/tests/render_2_1.rs
alexm abae39bd54
Pipeline / check (pull_request) Failing after 12m11s
Pipeline / docs (pull_request) Skipped
Pipeline / nightly (pull_request) Skipped
Pipeline / release (pull_request) Skipped
chore: relicense under Apache-2.0
Replace the Prosperity Public License 3.0.0 with the Apache License 2.0:
LICENSE.md, a new NOTICE.md, the Cargo license field, every SPDX header,
and the README's license and contributing sections.
2026-11-18 18:57:08 -05:00

517 lines
18 KiB
Rust

// SPDX-License-Identifier: Apache-2.0
// Copyright Scienting
// Source: https://git.scient.ing/education/coursebank
//! What 2.1 renders: the lecture page, the glossary page, and the student
//! reports, and what it must never render for a student.
mod common;
use std::path::Path;
use common::{design, v21_course};
use coursebank::assessment::{AssessmentFile, Form};
use coursebank::catalog::Catalog;
use coursebank::lecture::{PageOptions, Style, glossary_markdown, page_markdown};
use coursebank::responses::{Response, ResponseSet};
use coursebank::typst::config::{RenderConfig, Variant};
/// The example lecture page in the Plain style, which is the style the
/// preview was written in.
fn plain_page(catalog: &Catalog) -> String {
let options = PageOptions {
style: Style::Plain,
..PageOptions::default()
};
page_markdown(&catalog.course, "l09", &options).expect("renders")
}
/// A page line with its link targets removed: `[gap](glossary.html#x)`
/// becomes `[gap]`, which is how the prototype's preview writes a link.
fn unlinked(line: &str) -> String {
let mut out = String::new();
let mut rest = line;
while let Some(at) = rest.find("](") {
out.push_str(&rest[..=at]);
let after = &rest[at + 2..];
match after.find(')') {
Some(close) => rest = &after[close + 1..],
None => {
rest = after;
break;
}
}
}
out.push_str(rest);
out
}
#[test]
fn the_lecture_page_has_the_content_and_order_of_the_preview() {
let catalog = Catalog::load(&v21_course("page-snapshot")).unwrap();
let rendered: Vec<String> = plain_page(&catalog)
.lines()
.map(unlinked)
.filter(|l| !l.trim().is_empty())
.collect();
let preview_text =
std::fs::read_to_string(design().join("examples/v21/lecture-page-preview.md")).unwrap();
// The prototype prints a target reference as the raw id; coursebank prints
// its number on the page, as the 2.0 readings page always has.
let preview_text = preview_text.replace("(T t-align-fill-matrix)", "(T 3)");
let preview: Vec<&str> = preview_text
.lines()
.filter(|l| !l.trim().is_empty() && !l.starts_with("<!--"))
.collect();
// Every preview line appears, in the preview's order.
let mut at = 0;
for line in &preview {
match rendered[at..].iter().position(|r| r == line) {
Some(offset) => at += offset + 1,
None => panic!(
"missing or out of order: {line:?}\n\nrendered:\n{}",
rendered.join("\n")
),
}
}
// And the page adds only what the specification asks for beyond the
// prototype: the workload line, and the reading's summary and skip notes.
let extra: Vec<&String> = rendered
.iter()
.filter(|r| !preview.contains(&r.as_str()))
.collect();
assert_eq!(
extra,
vec![
"About 40 minutes of assigned reading.",
" Introduces the alignment matrix and [the global alignment recurrence], then \
contrasts the global and local fills.",
" Gloss the affine-gap extension. It comes in a later lecture.",
],
);
}
#[test]
fn the_quarto_page_anchors_new_terms_and_links_to_them() {
let catalog = Catalog::load(&v21_course("page-quarto")).unwrap();
let page = page_markdown(&catalog.course, "l09", &PageOptions::default()).unwrap();
assert!(page.contains("[**gap penalty**]{#glossary-term-gap-penalty} $d$:"));
assert!(page.contains("[gap penalty](#glossary-term-gap-penalty)"));
assert!(page.contains("### the global alignment recurrence {#glossary-eq-global-recurrence}"));
assert!(page.contains("(@) **Define the alignment matrix"));
assert!(page.contains("- $F(i,j)$: the best score"));
assert!(page.contains("- [Lecture brief](https://example.edu/briefs/l09)"));
}
#[test]
fn a_later_lecture_lists_earlier_terms_with_the_lecture_that_introduced_them() {
let root = v21_course("page-later");
std::fs::write(
root.join("lectures/l10.yaml"),
"lectures:\n l10:\n title: Database search\n teaches: [lo-search]\n",
)
.unwrap();
std::fs::write(
root.join("objectives/lo-search.yaml"),
"learning_objectives:\n lo-search: { text: Search a database., level_ceiling: 2 }\n\
learning_targets:\n t-search-seeds:\n text: Explain why a search starts from \
short exact matches.\n objective: lo-search\n level_ceiling: 2\n terms: \
[term-gap-penalty, term-seed]\nterms:\n term-seed: { term: seed, definition: A short \
exact match a search extends. }\n",
)
.unwrap();
let catalog = Catalog::load(&root).unwrap();
let course = &catalog.course;
assert_eq!(course.first_lecture("term-gap-penalty"), Some("l09"));
assert_eq!(course.first_lecture("term-seed"), Some("l10"));
assert_eq!(course.first_lecture("val-per-decade"), None);
let page = page_markdown(course, "l10", &PageOptions::default()).unwrap();
assert!(page.contains("[**seed**]{#glossary-term-seed}"), "{page}");
assert!(
page.contains(
"Terms from earlier lectures: [gap penalty](glossary.html#glossary-term-gap-penalty) \
(l09)"
),
"{page}"
);
}
#[test]
fn the_glossary_page_lists_terms_alphabetically_with_their_first_lecture() {
let catalog = Catalog::load(&v21_course("glossary-page")).unwrap();
let page = glossary_markdown(&catalog.course, &PageOptions::default());
let terms: Vec<&str> = page
.lines()
.filter_map(|l| l.strip_prefix("- [**"))
.map(|l| l.split("**]").next().unwrap())
.collect();
assert_eq!(
terms,
vec![
"alignment matrix",
"decade",
"gap",
"gap penalty",
"global alignment",
"local alignment",
"substitution score",
"traceback",
]
);
assert!(page.contains("*First in l09: Pairwise alignment.*"));
// A link between entries stays on this page.
assert!(page.contains("aligned against a [gap](#glossary-term-gap)"));
assert!(page.contains("## Equations"));
assert!(
page.contains("- free energy per ten-fold concentration ratio at 37 °C: about 6 kJ/mol")
);
}
/// A second item that encodes the same registry misconception, so a student
/// who misses both has one mistake behind two answers.
const SECOND_ITEM: &str = "
- id: q-align-equal-matches
status: draft
level: 2
stem: 'Two alignments of one pair have equal matches. Which scores higher?'
learning_targets: [t-align-score-columns]
options:
- { id: o-fewer-gaps, text: 'The one with fewer gaps.', correct: true }
- { id: o-tie, text: 'Neither; equal matches mean equal scores.', misconception_id: mis-only-matches-count }
";
/// The record both items were given on.
const RECORD: &str = "
assessment: { id: alignment-quiz, title: Alignment quiz }
items:
- { number: 1, item: q-align-which-scores-higher, learning_targets: [t-align-score-columns] }
- { number: 2, item: q-align-equal-matches, learning_targets: [t-align-score-columns] }
";
/// One response row.
fn response(student: &str, number: u32, item: &str, chosen: &str, credit: f64) -> Response {
Response {
administration_id: "BIOSC 1540/2027s/alignment-quiz".into(),
course: "BIOSC 1540".into(),
term: "2027s".into(),
assessment_id: "alignment-quiz".into(),
date: None,
form: None,
form_position: None,
student_key: student.into(),
sid: None,
name: None,
email: None,
section: None,
item_number: number,
item_ref: Some(item.into()),
item_version: None,
variant: None,
selected: vec![chosen.into()],
selected_source: vec![chosen.into()],
eliminated: vec![],
eliminated_source: vec![],
correct: Some(credit >= 0.999),
credit,
points_possible: 1.0,
score: credit,
response_time_seconds: None,
level: None,
learning_targets: vec!["t-align-score-columns".into()],
topics: vec![],
bonus: false,
dropped: false,
dropped_full_credit: false,
}
}
/// The example with a second item, and the record and responses for a student
/// who missed both by the same mistake.
fn administered(tag: &str) -> (Catalog, AssessmentFile, ResponseSet) {
let root = v21_course(tag);
let bank = root.join("banks/alignment.yaml");
let mut text = std::fs::read_to_string(&bank).unwrap();
text.push_str(SECOND_ITEM);
std::fs::write(&bank, text).unwrap();
let catalog = Catalog::load(&root).unwrap();
let record: AssessmentFile = serde_yaml_ng::from_str(RECORD).unwrap();
let mut set = ResponseSet::new();
set.rows = vec![
response(
"s1",
1,
"q-align-which-scores-higher",
"o-matches-only",
0.0,
),
response("s1", 2, "q-align-equal-matches", "o-tie", 0.0),
response(
"s2",
1,
"q-align-which-scores-higher",
"o-columns-all-count",
1.0,
),
response("s2", 2, "q-align-equal-matches", "o-fewer-gaps", 1.0),
];
(catalog, record, set)
}
/// The Markdown report for the student who missed both.
fn markdown_report(catalog: &Catalog, record: &AssessmentFile, set: &ResponseSet) -> String {
let cohort = coursebank::students::summarize(set, &catalog.course, Some(catalog), None);
let summary = cohort
.students
.iter()
.find(|s| s.student_key == "s1")
.unwrap();
coursebank::report::student(
summary,
&cohort,
&catalog.course,
record,
&coursebank::report::StudentOptions::default(),
)
}
/// The PDF report's payload for the student who missed both, as Typst source.
fn typst_report(catalog: &Catalog, set: &ResponseSet) -> String {
let cohort = coursebank::students::summarize(set, &catalog.course, Some(catalog), None);
let summary = cohort
.students
.iter()
.find(|s| s.student_key == "s1")
.unwrap();
let diagnostic = coursebank::diagnostic::student(
summary,
&cohort,
catalog,
set,
None,
&coursebank::diagnostic::Options::default(),
);
let config = RenderConfig::for_variant(Variant::StudentReport);
coursebank::typst::diagnostic::student_value(&diagnostic, &config).to_typst(0)
}
#[test]
fn a_student_report_explains_the_target_and_groups_misses_by_misconception() {
let (catalog, record, set) = administered("report-markdown");
let report = markdown_report(&catalog, &record, &set);
assert!(
report.contains(
"What meeting it looks like: An alignment's score is the sum over its columns."
),
"{report}"
);
// The registry's belief and correction, for an option that names the
// misconception and says nothing itself.
assert!(
report.contains(
"This answer reflects a common mistake: *An alignment score counts the matching \
positions"
),
"{report}"
);
assert!(
report.contains("Every column counts: matches add"),
"{report}"
);
// Both misses share the misconception, so they are grouped under it.
assert!(
report.contains("## The same mistake, more than once\n\n**Questions 1, 2**:"),
"{report}"
);
}
#[test]
fn the_pdf_report_carries_the_same_explanation_mistake_and_grouping() {
let (catalog, _, set) = administered("report-typst");
let payload = typst_report(&catalog, &set);
assert!(payload.contains("explanation:"), "{payload}");
assert!(payload.contains("mistake: ("), "{payload}");
assert!(payload.contains("mis-only-matches-count"), "{payload}");
let compact: String = payload.split_whitespace().collect();
assert!(
compact.contains("mistakes:((id:\"mis-only-matches-count\""),
"{payload}"
);
assert!(compact.contains("questions:(1,2,)"), "{payload}");
}
/// Instructor-facing text that must never reach a student: `authoring`,
/// `notes_private`, `evidence`, `conflicts`, and `status`.
fn private_text(catalog: &Catalog) -> Vec<String> {
let course = &catalog.course;
let mut out = Vec::new();
for target in course.learning_targets.values() {
if let Some(a) = &target.authoring {
out.extend(a.ceiling_item.clone());
out.extend(a.number_work.clone());
out.extend(a.supplied.iter().cloned());
out.extend(a.constraints.iter().cloned());
out.extend(a.examples.iter().cloned());
}
}
for m in course.misconceptions.values() {
out.extend(m.evidence.iter().filter_map(|e| e.detail.clone()));
}
for v in course.values.values() {
out.extend(v.conflicts.iter().cloned());
}
out.extend(
course
.terms
.values()
.filter_map(|t| t.notes_private.clone()),
);
out.extend(
course
.equations
.values()
.filter_map(|e| e.notes_private.clone()),
);
out.extend(
course
.values
.values()
.filter_map(|v| v.notes_private.clone()),
);
out.extend(
course
.misconceptions
.values()
.filter_map(|m| m.notes_private.clone()),
);
// A short note can repeat words a student-facing field also uses (`supplied:
// the scoring scheme` beside a target that says "the scoring scheme"), and
// finding those on a page proves nothing. Only text that appears nowhere a
// student is meant to read is a test of the rule.
let public: Vec<String> = course
.student_prose()
.iter()
.map(|p| p.text.to_string())
.chain(catalog.entries.iter().flat_map(|e| {
std::iter::once(e.item.stem.clone())
.chain(e.item.options.iter().map(|o| o.text.clone()))
}))
.collect();
out.retain(|secret| !public.iter().any(|p| p.contains(secret.as_str())));
out
}
#[test]
fn instructor_fields_never_reach_a_student_page_report_or_export() {
let (mut catalog, record, set) = administered("rule-5");
// The example has no private notes, so give every registry entry one.
let course = &mut catalog.course;
for (id, t) in course.terms.iter_mut() {
t.notes_private = Some(format!("PRIVATE NOTE on {id}"));
}
for (id, e) in course.equations.iter_mut() {
e.notes_private = Some(format!("PRIVATE NOTE on {id}"));
}
for (id, v) in course.values.iter_mut() {
v.notes_private = Some(format!("PRIVATE NOTE on {id}"));
}
for (id, m) in course.misconceptions.iter_mut() {
m.notes_private = Some(format!("PRIVATE NOTE on {id}"));
}
// Every course in the wild that has a proposed entry would print the word
// somewhere if status leaked; the example has two.
let secrets = private_text(&catalog);
assert!(secrets.len() > 10, "{secrets:#?}");
let form = Form {
id: "A".into(),
seed: 0,
shuffle_items: false,
shuffle_options: false,
};
let mut outputs: Vec<(String, String)> = Vec::new();
for style in [Style::Quarto, Style::Plain] {
let options = PageOptions {
style,
..PageOptions::default()
};
outputs.push((
format!("lecture page ({style:?})"),
page_markdown(&catalog.course, "l09", &options).unwrap(),
));
outputs.push((
format!("glossary page ({style:?})"),
glossary_markdown(&catalog.course, &options),
));
}
outputs.push((
"readings page".into(),
coursebank::lecture::readings_markdown(&catalog.course, "l09", Style::Quarto).unwrap(),
));
outputs.push((
"student report".into(),
markdown_report(&catalog, &record, &set),
));
outputs.push(("student PDF report".into(), typst_report(&catalog, &set)));
let qti =
coursebank::qti::build(&catalog, &record, &coursebank::qti::QtiOptions::default()).unwrap();
outputs.push(("Canvas quiz".into(), qti.quiz_xml));
for variant in [
coursebank::practice::Variant::Worksheet,
coursebank::practice::Variant::Solutions,
] {
let options = coursebank::practice::Options {
form: form.clone(),
variant,
answer_space: false,
};
outputs.push((
format!("practice {variant:?}"),
coursebank::practice::render(&catalog, &record, &options).unwrap(),
));
}
let site =
coursebank::site::render(&catalog, &record, coursebank::site::Options::new(form)).unwrap();
outputs.push(("site page".into(), site.page));
outputs.push(("site questions".into(), site.questions_qmd));
for (name, text) in &outputs {
for secret in &secrets {
assert!(
!text.contains(secret.as_str()),
"{name} prints instructor-facing text {secret:?}"
);
}
assert!(
!text.contains("proposed"),
"{name} prints an entry's status"
);
}
}
#[test]
fn the_cli_writes_the_page_and_the_glossary() {
let root = v21_course("cli-page");
let run = |args: &[&str]| {
std::process::Command::new(env!("CARGO_BIN_EXE_coursebank"))
.arg("-C")
.arg(&root)
.args(args)
.output()
.unwrap()
};
let page = run(&["lecture", "page", "l09", "--style", "plain"]);
assert!(page.status.success());
assert!(String::from_utf8_lossy(&page.stdout).starts_with("# l09: Pairwise alignment"));
let out = root.join("glossary.qmd");
let glossary = run(&["lecture", "glossary", "--out", out.to_str().unwrap()]);
assert!(glossary.status.success());
assert!(Path::new(&out).is_file());
}