Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
78 changes: 39 additions & 39 deletions FEATURES.md

Large diffs are not rendered by default.

134 changes: 134 additions & 0 deletions crates/netscenario-backend-kernel/tests/coverage.rs
Original file line number Diff line number Diff line change
Expand Up @@ -118,3 +118,137 @@ fn the_reader_of_links_finds_a_missing_link_and_a_missing_file() {
let docs = Path::new(env!("CARGO_MANIFEST_DIR")).join("../../docs");
assert!(!docs.join("../crates/no-such-crate/tests/a.rs").is_file());
}

/// One row of a table of the page: the section it is in, its label and its three cells (Kernel, Engine, Proxy).
struct Row {
section: String,
label: String,
cells: Vec<String>,
}

fn rows_of(markdown: &str) -> Vec<Row> {
let mut section = String::new();
let mut rows = Vec::new();
for line in markdown.lines() {
if let Some(title) = line.strip_prefix("## ") {
title.trim().clone_into(&mut section);
}
let Some(inner) = line.strip_prefix('|') else {
continue;
};
let cells: Vec<String> = inner
.trim_end_matches('|')
.split('|')
.map(|cell| cell.trim().to_owned())
.collect();
let separator = cells
.iter()
.all(|c| c.chars().all(|ch| matches!(ch, '-' | ':' | ' ')));
if cells.len() >= 4 && !separator && cells[1] != "Kernel" {
rows.push(Row {
section: section.clone(),
label: cells[0].clone(),
cells: cells[1..4].to_vec(),
});
}
}
rows
}

/// The release of a faithful mark (`✔ 0.2 (...)` is `Some(2)`), or `None` for any other cell.
fn faithful_release(cell: &str) -> Option<u32> {
let rest = cell.strip_prefix("✔ 0.")?;
rest.split(|c: char| !c.is_ascii_digit())
.next()?
.parse()
.ok()
}

/// Every link of a cell: `[text](target)` gives `target`.
fn links_in(cell: &str) -> Vec<&str> {
cell.split("](")
.skip(1)
.filter_map(|part| part.split(')').next())
.collect()
}

fn is_a_test(target: &str) -> bool {
let path = target.split('#').next().unwrap_or(target);
path.split('/').any(|part| part == "tests")
|| path
.rsplit('/')
.next()
.is_some_and(|name| name.starts_with("test_"))
}

/// A faithful mark of a release that is out is proven: its Kernel cell links to a test, for every row of the page and not only for
/// the rows that the code declares (`Feature`). A mark of a later release is a plan (the page says so) and has no link yet; the
/// release pull request raises the version of the crates, and from then on the marks of that release need theirs. Links in any
/// cell of any column must lead to a file.
#[test]
fn every_faithful_mark_of_a_released_version_links_to_a_test_and_no_link_leads_nowhere() {
let docs = Path::new(env!("CARGO_MANIFEST_DIR")).join("../../docs");
let minor: u32 = env!("CARGO_PKG_VERSION")
.split('.')
.nth(1)
.unwrap()
.parse()
.unwrap();
let rows = rows_of(COVERAGE);
assert!(
rows.len() > 50,
"the table was not read: {} rows",
rows.len()
);
for row in &rows {
for cell in &row.cells {
for target in links_in(cell) {
let path = target.split('#').next().unwrap();
if !path.starts_with("http") && !path.is_empty() {
assert!(
docs.join(path).exists(),
"'{}' links to {target}, which is not there",
row.label
);
}
}
}
let kernel = &row.cells[0];
if faithful_release(kernel).is_some_and(|release| release <= minor) {
let links = links_in(kernel);
assert!(
!links.is_empty(),
"'{}' is faithful in release 0.{minor} and has no link: {kernel}",
row.label
);
// Where a run works, the proof is the CI; for a feature it is a test
if row.section != "Where it can run" {
assert!(
links.iter().any(|link| is_a_test(link)),
"'{}' links to no test: {kernel}",
row.label
);
}
}
}
}

/// Canary: the reader of the page and the rules find what they are for.
#[test]
fn the_rules_for_the_marks_find_a_plan_a_proof_and_a_missing_test() {
let page = "## Topology\n| Feature | Kernel | Engine | Proxy |\n| --- | --- | --- | --- |\n| A | ✔ 0.1 ([t](../crates/x/tests/a.rs)) | ✔ 0.4 | ✘ |\n| B | ✔ 0.6 | ✔ 0.6 | ✘ |\n## Where it can run\n| Place | Kernel | Engine | Proxy |\n| P | ✔ 0.1 ([ci](../.github/workflows/ci.yml)) | · | · |\n";
let rows = rows_of(page);
assert_eq!(rows.len(), 3);
assert_eq!(rows[0].section, "Topology");
assert_eq!(rows[2].section, "Where it can run");
assert_eq!(faithful_release(&rows[0].cells[0]), Some(1));
assert_eq!(faithful_release(&rows[1].cells[0]), Some(6));
assert_eq!(faithful_release("~ 0.2"), None);
assert_eq!(faithful_release("✘"), None);
assert_eq!(links_in(&rows[0].cells[0]), ["../crates/x/tests/a.rs"]);
assert_eq!(links_in(&rows[1].cells[0]), Vec::<&str>::new());
assert!(is_a_test("../crates/x/tests/a.rs#L3"));
assert!(is_a_test("../python/netscenario/tests/test_a.py"));
assert!(!is_a_test("decisions/D-083.md"));
assert!(!is_a_test("../.github/workflows/ci.yml"));
}
181 changes: 178 additions & 3 deletions crates/netscenario-core/src/backend.rs
Original file line number Diff line number Diff line change
Expand Up @@ -672,7 +672,7 @@ pub trait Backend {
/// [`Error::Backend`] if the link does not exist, or the backend has no interfaces to name (the default).
fn interface_name(&self, _link: LinkHandle, _end: usize) -> Result<String, Error> {
Err(Error::Backend {
backend: "this".to_owned(),
backend: self.name().to_owned(),
action: "name an interface".to_owned(),
message: "the backend cannot do it".to_owned(),
})
Expand Down Expand Up @@ -706,7 +706,7 @@ pub trait Backend {
_signal: ProgramSignal,
) -> Result<(), Error> {
Err(Error::Backend {
backend: "this".to_owned(),
backend: self.name().to_owned(),
action: "signal a program".to_owned(),
message: "the backend cannot do it".to_owned(),
})
Expand All @@ -726,7 +726,7 @@ pub trait Backend {
_port: u16,
) -> Result<bool, Error> {
Err(Error::Backend {
backend: "this".to_owned(),
backend: self.name().to_owned(),
action: "look at the ports of a node".to_owned(),
message: "the backend cannot do it".to_owned(),
})
Expand All @@ -748,3 +748,178 @@ pub trait Backend {
/// [`Error::Backend`] if something could not be removed. The message says what is left.
fn teardown(&mut self) -> Result<(), Error>;
}

#[cfg(test)]
mod tests {
use super::*;

/// A backend that does only what every backend must, and leaves the rest to the defaults of the trait. What a user gets from
/// a backend that lacks a feature is what these defaults say, so each is checked: a default that says "yes" or says nothing
/// would let a scenario run on a backend that cannot reproduce it.
struct Bare;

impl Backend for Bare {
fn name(&self) -> &'static str {
"bare"
}
fn capabilities(&self) -> Capabilities {
Capabilities::new("bare")
}
fn create_node(&mut self, _name: &Name) -> Result<NodeHandle, Error> {
Ok(NodeHandle(0))
}
fn create_link(
&mut self,
_name: &Name,
_between: [NodeHandle; 2],
) -> Result<LinkHandle, Error> {
Ok(LinkHandle(0))
}
fn apply(
&mut self,
_link: LinkHandle,
_direction: Direction,
_impairments: &Impairments,
_seed: Option<u64>,
) -> Result<(), Error> {
Ok(())
}
fn start_program(
&mut self,
_node: NodeHandle,
_program: &Program,
) -> Result<ProgramHandle, Error> {
Ok(ProgramHandle(0))
}
fn address(&self, _link: LinkHandle, _end: usize) -> Result<Ipv4Addr, Error> {
Ok(Ipv4Addr::LOCALHOST)
}
fn describe(&self) -> BackendInfo {
BackendInfo {
name: "bare".to_owned(),
details: BTreeMap::new(),
}
}
fn poll_program(
&mut self,
_program: ProgramHandle,
_wait: Duration,
) -> Result<ProgramState, Error> {
Ok(ProgramState::default())
}
fn send_line(&mut self, _program: ProgramHandle, _line: &str) -> Result<(), Error> {
Ok(())
}
fn teardown(&mut self) -> Result<(), Error> {
Ok(())
}
}

const LINK: LinkHandle = LinkHandle(1);
const NODE: NodeHandle = NodeHandle(1);

/// The three parts of a refusal, or a panic with what the call gave instead.
fn refusal<T: std::fmt::Debug>(result: Result<T, Error>) -> (String, String, String) {
match result {
Err(Error::Backend {
backend,
action,
message,
}) => (backend, action, message),
other => panic!("a backend without the feature must refuse, and it gave {other:?}"),
}
}

/// Every default that refuses says which backend refuses, what it was asked and why: the message is what the user reads
/// ("the bare backend failed to ..."). Canary: three of them said "this" for the backend, which no reader can place.
#[test]
fn a_backend_without_a_feature_refuses_and_names_itself_and_the_action() {
let mut bare = Bare;
let route = NodeRoute {
family: IpFamily::V4,
destination: None,
metric: 100,
next_hops: Vec::new(),
};
let name = Name::new("a").unwrap();
let refusals = [
refusal(bare.change(LINK, Direction::Forward, &Impairments::default())),
refusal(bare.set_outage(LINK, Direction::Forward, true)),
refusal(bare.set_link(LINK, false)),
refusal(bare.set_ip_families(true, true)),
refusal(bare.set_node_address(NODE, IpAddr::V4(Ipv4Addr::LOCALHOST))),
refusal(bare.create_link_through_fabric(&name, [NODE, NODE])),
refusal(bare.set_link_mtu(LINK, 1400)),
refusal(bare.set_forwarding(NODE, true)),
refusal(bare.add_route(NODE, &route)),
refusal(bare.address_v6(LINK, 0)),
refusal(bare.interface_name(LINK, 0)),
refusal(bare.signal_program(ProgramHandle(0), ProgramSignal::Term)),
refusal(bare.port_bound(NODE, PortKind::Udp, 4433)),
];
let mut actions = std::collections::BTreeSet::new();
for (backend, action, message) in refusals {
assert_eq!(backend, "bare", "{action}: {message}");
assert!(!action.is_empty() && !message.is_empty());
actions.insert(action);
}
assert_eq!(
actions.len(),
13,
"each refusal says what it was asked: {actions:?}"
);
// What the user reads
let (backend, action, message) = refusal(bare.set_link(LINK, false));
let error = Error::Backend {
backend,
action,
message,
};
assert_eq!(
error.to_string(),
"the bare backend failed to take a link down or bring it up: this backend does not take links down"
);
}

/// The defaults that have nothing to say are neutral: they accept, or answer that the backend cannot count, and a run then
/// leaves the comparison out instead of failing on it.
#[test]
fn a_backend_that_counts_nothing_says_so_and_accepts_the_steps_that_need_no_work() {
let mut bare = Bare;
let scenario = Scenario::from_yaml(
"version: 0\nname: bare\nduration: 1s\ntopology:\n nodes: [a, b]\n links:\n - { id: l, between: [a, b] }\nworkloads:\n - { id: w, kind: udp-cbr, from: a, to: b, rate: 1mbit, packet-size: 1000b }\n",
"n.yaml",
)
.unwrap();
assert!(bare.check_values(&scenario).is_ok());
assert!(bare.plan_states(LINK, Direction::Forward, &[]).is_ok());
assert!(bare.plan_outage(LINK, Direction::Reverse).is_ok());
assert_eq!(bare.notes(), Vec::<String>::new());
assert_eq!(bare.queue_packets(LINK, Direction::Forward).unwrap(), None);
assert_eq!(bare.queue_backlog(LINK, Direction::Forward).unwrap(), None);
assert!(
bare.node_counts(LINK, Direction::Forward)
.unwrap()
.is_none()
);
assert!(
bare.queue_stats(LINK, Direction::Forward)
.unwrap()
.is_none()
);
assert!(bare.set_ip_families(true, false).is_ok());
assert!(bare.finish_network().is_ok());
}

#[test]
fn a_signal_is_the_signal_of_the_model() {
assert_eq!(
ProgramSignal::from(netscenario_model::Signal::Int),
ProgramSignal::Int
);
assert_eq!(
ProgramSignal::from(netscenario_model::Signal::Term),
ProgramSignal::Term
);
}
}
Loading