Files
coursebank/tests/schema_2_1.rs
T
alexmandClaude 51a2fd235f feat(schema): 2.1 types, fragments, and JSON Schemas
Add the term, equation, value, and misconception registries
(src/model/course/glossary.rs) and the new optional fields on objectives,
targets, lectures, readings, bank options, and policy. Load registry
entries from objective files, glossary.yaml, and course.yaml, with one
definition site per id as for every other registry. Port every edit in
docs/design/2.1/build_schemas.py into the hand-written schema builders,
add glossary.schema.json, and test the generated schemas against the
targets; the only differences are two 2.0 spellings the code already had.

The 2.0 example fragments load and validate unchanged. The 2.1 example
bank gains `status: draft`, which every coursebank item requires.
tests/docs.rs skips docs/design/, which holds design records rather than
guide pages.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-16 11:55:18 -05:00

276 lines
9.7 KiB
Rust

// SPDX-License-Identifier: Prosperity-3.0.0
// Copyright Scienting
// Source: https://git.scient.ing/education/coursebank
//! The 2.1 schema against its specification in `docs/design/2.1/`.
//!
//! The examples there are the fixtures, read in place, so the specification and
//! these tests cannot drift apart: `examples/v20/` must load unchanged,
//! `examples/v21/` uses every new field, and `schemas/` is the JSON Schema each
//! generated file must equal.
use std::path::{Path, PathBuf};
use coursebank::catalog::Catalog;
use coursebank::course::CourseFile;
use coursebank::jsonschema::{self, Kind};
use serde_json::Value;
/// `docs/design/2.1/`.
fn design() -> PathBuf {
PathBuf::from(env!("CARGO_MANIFEST_DIR")).join("docs/design/2.1")
}
/// A fresh, empty directory under the system temp dir.
fn scratch(tag: &str) -> PathBuf {
let dir = std::env::temp_dir().join(format!("coursebank-2-1-{tag}-{}", std::process::id()));
let _ = std::fs::remove_dir_all(&dir);
std::fs::create_dir_all(&dir).unwrap();
dir
}
/// Copies a directory tree.
fn copy_tree(from: &Path, to: &Path) {
std::fs::create_dir_all(to).unwrap();
for entry in std::fs::read_dir(from).unwrap() {
let path = entry.unwrap().path();
let target = to.join(path.file_name().unwrap());
if path.is_dir() {
copy_tree(&path, &target);
} else {
std::fs::copy(&path, &target).unwrap();
}
}
}
/// The JSON pointers at which two values differ.
fn differences(path: &str, generated: &Value, target: &Value, out: &mut Vec<String>) {
match (generated, target) {
(Value::Object(a), Value::Object(b)) => {
for key in a.keys().chain(b.keys().filter(|k| !a.contains_key(*k))) {
let here = format!("{path}/{}", key.replace('~', "~0").replace('/', "~1"));
match (a.get(key), b.get(key)) {
(Some(x), Some(y)) => differences(&here, x, y, out),
(Some(_), None) => out.push(format!("{here} (only generated)")),
(None, Some(_)) => out.push(format!("{here} (only in the target)")),
(None, None) => {}
}
}
}
(Value::Array(a), Value::Array(b)) if a.len() == b.len() => {
for (i, (x, y)) in a.iter().zip(b).enumerate() {
differences(&format!("{path}/{i}"), x, y, out);
}
}
_ if generated == target => {}
_ => out.push(path.to_string()),
}
}
/// Differences that are known and kept, with the reason.
///
/// Both are spellings in 2.0 descriptions that the code already had before 2.1:
/// `schemas-original/` was generated by a build that spelled them the American
/// way, and the 2.1 targets were built from it.
const KNOWN: &[(&str, &str)] = &[
(
"calibration.schema.json",
"/properties/items/additionalProperties/properties/variants/items/properties/option_stats\
/description",
),
(
"course.schema.json",
"/properties/policy/properties/grade_scale/items/properties/group/description",
),
];
#[test]
fn every_generated_schema_matches_its_target() {
let mut unexpected = Vec::new();
for kind in Kind::ALL {
let name = kind.filename();
let text = std::fs::read_to_string(design().join("schemas").join(name))
.unwrap_or_else(|e| panic!("{name}: {e}"));
let target: Value = serde_json::from_str(&text).unwrap();
let mut found = Vec::new();
differences("", &jsonschema::schema(kind), &target, &mut found);
for pointer in found {
if !KNOWN.iter().any(|(file, p)| *file == name && *p == pointer) {
unexpected.push(format!("{name}: {pointer}"));
}
}
}
assert!(
unexpected.is_empty(),
"generated schemas differ from docs/design/2.1/schemas:\n {}",
unexpected.join("\n ")
);
}
#[test]
fn the_known_differences_are_still_there() {
// If one of these is fixed, the allow-list should shrink with it.
for (file, pointer) in KNOWN {
let kind = Kind::ALL
.into_iter()
.find(|k| k.filename() == *file)
.unwrap();
let generated = jsonschema::schema(kind);
let text = std::fs::read_to_string(design().join("schemas").join(file)).unwrap();
let target: Value = serde_json::from_str(&text).unwrap();
assert_ne!(
generated.pointer(pointer),
target.pointer(pointer),
"{file}{pointer}"
);
}
}
/// The 2.0 fragments, completed into a course with the ids they cite.
fn v20_course(tag: &str) -> PathBuf {
let root = scratch(tag);
std::fs::write(
root.join("course.yaml"),
"schema_version: '2.0'\ncourse: { code: BIOSC 1540, title: Computational Biology, term: \
2026f }\nunits: [{ id: u1, title: Sequences and alignment }]\nreferences:\n \
durbin1998biological: { title: Biological Sequence Analysis }\n",
)
.unwrap();
std::fs::create_dir_all(root.join("lectures")).unwrap();
std::fs::create_dir_all(root.join("objectives")).unwrap();
let v20 = design().join("examples/v20");
std::fs::copy(v20.join("l09.yaml"), root.join("lectures/l09.yaml")).unwrap();
std::fs::copy(
v20.join("lo-alignment-recurrence.yaml"),
root.join("objectives/lo-alignment-recurrence.yaml"),
)
.unwrap();
std::fs::write(
root.join("objectives/lo-alignment-scoring.yaml"),
"learning_objectives:\n lo-alignment-scoring: { text: Score an alignment., unit: u1, \
level_ceiling: 3 }\nlearning_targets:\n t-align-matrix-terms: { text: Define the \
matrix., objective: lo-alignment-scoring, level_ceiling: 1 }\n \
t-align-local-vs-global: { text: Compare local and global., objective: \
lo-alignment-scoring, level_ceiling: 2 }\n",
)
.unwrap();
root
}
#[test]
fn the_2_0_fragments_load_and_validate_unchanged() {
let root = v20_course("v20-load");
let course = CourseFile::load_dir(&root).expect("2.0 fragments load");
let issues = course.validate();
assert!(issues.is_empty(), "{issues:#?}");
assert!(course.terms.is_empty() && course.equations.is_empty());
}
/// The 2.1 example course, copied so a test may change it.
pub fn v21_course(tag: &str) -> PathBuf {
let root = scratch(tag);
copy_tree(&design().join("examples/v21"), &root);
let _ = std::fs::remove_file(root.join("lecture-page-preview.md"));
root
}
#[test]
fn the_2_1_example_loads_every_new_field() {
let root = v21_course("v21-load");
let catalog = Catalog::load(&root).expect("the 2.1 example loads");
let course = &catalog.course;
assert_eq!(course.terms.len(), 8);
assert_eq!(course.equations.len(), 1);
assert_eq!(course.values.len(), 2);
assert_eq!(course.misconceptions.len(), 2);
// Where each entry came from: the objective file, or glossary.yaml.
assert_eq!(
course.origin("term-gap").map(|(_, p)| p.to_path_buf()),
Some(PathBuf::from("objectives/lo-alignment-scoring.yaml"))
);
assert_eq!(
course
.origin("val-per-decade")
.map(|(_, p)| p.to_path_buf()),
Some(PathBuf::from("glossary.yaml"))
);
let target = &course.learning_targets["t-align-fill-matrix"];
assert!(target.explanation.is_some());
assert_eq!(target.equations, vec!["eq-global-recurrence".to_string()]);
assert!(target.authoring.as_ref().unwrap().ceiling_item.is_some());
let lecture = &course.lectures["l09"];
assert!(lecture.description.is_some());
assert_eq!(lecture.materials.len(), 3);
assert_eq!(lecture.readings[0].minutes, Some(40));
let policy = &course.policy;
assert_eq!(policy.levels["3"].name, "Application");
assert_eq!(policy.blueprints["module"].level_counts["2"], 18);
assert_eq!(policy.target_text_forbid.len(), 3);
assert_eq!(
policy.exam_conditions.as_ref().unwrap().seconds_per_item,
Some(120.0)
);
let item = catalog.get("q-align-which-scores-higher").expect("item");
assert_eq!(
item.item.options[1].misconception_id.as_deref(),
Some("mis-only-matches-count")
);
}
#[test]
fn the_migration_output_loads_as_a_glossary_fragment() {
let root = scratch("migration-output");
std::fs::write(
root.join("course.yaml"),
"course: { code: X, title: Y, term: Z }\nreferences:\n KKW: { title: The Molecules of \
Life }\n",
)
.unwrap();
std::fs::copy(
design().join("examples/migration/glossary.expected.yaml"),
root.join("glossary.yaml"),
)
.unwrap();
let course = CourseFile::load_dir(&root).expect("loads");
assert!(course.terms.contains_key("term-decade"));
assert!(course.values.contains_key("val-per-decade"));
}
#[test]
fn a_lecture_file_may_not_define_glossary_entries() {
let root = v20_course("v20-lecture-glossary");
std::fs::write(
root.join("lectures/l10.yaml"),
"lectures:\n l10: { title: Ten }\nterms:\n term-x: { term: x, definition: An x. }\n",
)
.unwrap();
let message = CourseFile::load_dir(&root).unwrap_err().to_string();
assert!(message.contains("may not define `terms`"), "{message}");
}
#[test]
fn a_glossary_id_defined_twice_names_both_files() {
let root = v21_course("v21-dup");
std::fs::write(
root.join("glossary.yaml"),
"terms:\n term-gap: { term: gap, definition: A dash. }\n",
)
.unwrap();
let message = CourseFile::load_dir(&root).unwrap_err().to_string();
assert!(
message.contains("term `term-gap` is defined in two places"),
"{message}"
);
assert!(message.contains("glossary.yaml"), "{message}");
assert!(
message.contains("objectives/lo-alignment-scoring.yaml"),
"{message}"
);
}