silk.testing.observation.
What a test reads of the host while the test runner watches it.
When to use#
The built-in test runner (silk.testing.runner) watches each test with this module, so it can
skip a passing test whose code and inputs did not change. The native providers of files,
environment variables, clocks, randomness, sockets and child processes report to it. You do not
call it from normal code.
Details#
A watch is one buffer that the runner owns, named by one word of the process. While no watch is
active, a report reads that word and returns. While one is active, note appends a read the
runner can repeat later (a file's contents, whether a path exists, a directory's listing, an
environment variable), and mark records that the test used something it cannot repeat, such
as the clock. Reports from several threads take turns on a lock.
A buffer starts with a 32-byte header: its data capacity, the bytes used, the marks (each a
u64, little-endian) and the lock word. Each note after it is its kind byte, then the root and
the path, each as a 4-byte little-endian length and its bytes. A note that does not fit sets
OVERFLOW instead.
Gotchas#
Only reads through the native providers are seen. A test that calls C directly, or reads the host some other way, reads unseen.
Import as TestObservation with import silk.testing.observation as TestObservation.
Public declarations: 19.
FILE#
pub const FILE: u8A note of a file's contents, read through a provider rooted at the note's root.
ENTRY#
pub const ENTRY: u8A note of whether a path exists, and whether it is a file or a directory, and its size.
LISTING#
pub const LISTING: u8A note of the names in a directory.
VARIABLE#
pub const VARIABLE: u8A note of one environment variable, named by the note's path. Its root is empty.
WRITE#
pub const WRITE: u8A note of a change to a path: a write, a new file or directory, or a removal.
TEMPORARY#
pub const TEMPORARY: u8A note of a directory the test created with a unique name. Notes under it are the test's own.
CLOCK#
pub const CLOCK: u64The mark of a clock read.
RANDOM#
pub const RANDOM: u64The mark of a random number from the host.
NETWORK#
pub const NETWORK: u64The mark of a socket or a name lookup.
PROCESS#
pub const PROCESS: u64The mark of a child process.
OVERFLOW#
pub const OVERFLOW: u64The mark of a note that did not fit in the buffer.
ENVIRONMENT#
pub const ENVIRONMENT: u64The mark of a list of environment variable names.
HOST#
pub const HOST: u64The mark of a read of the host: its system information, standard input, signals or the program's arguments.
HEADER#
pub const HEADER: usizeThe size of a buffer's header, before its notes.
start#
pub unsafe fn start(buffer: *mut u8) -> ()Makes buffer the active watch, so the reports that follow go to it.
Details#
buffer must hold a header (HEADER bytes) whose first word is the capacity of the data after
it, whose other words are zero, and it must stay valid until stop. start does not clear it;
the runner does.
Gotchas#
Only the test runner calls it, between tests.
stop#
pub fn stop() -> ()Ends the active watch. The reports that follow do nothing.
Gotchas#
Only the test runner calls it, between tests. A report on another thread that already read the buffer's address can still write to it, so the runner reads the buffer only after the test's threads have stopped.
watching#
pub fn watching() -> boolWhether a watch is active.
mark#
pub fn mark(reason: u64) -> ()Records, in the active watch, that the test used what reason names, which it cannot repeat.
Details#
reason is one of the marks, such as CLOCK. Without an active watch it does nothing.
note#
pub fn note(kind: u8, root: &[u8], path: &[u8]) -> ()Records, in the active watch, that the test read path of a provider rooted at root, as
kind says.
Details#
kind is one of FILE, ENTRY, LISTING, VARIABLE, WRITE or TEMPORARY. Without an active watch it
does nothing. When the note does not fit, it marks OVERFLOW.
Category: Testing.
Profiles: aarch64-apple-darwin, aarch64-unknown-linux-gnu, aarch64-unknown-linux-gnu-no-libc, x86_64-unknown-linux-gnu, x86_64-unknown-linux-gnu-no-libc, wasm32-unknown-unknown, wasm32-wasip1, wasm32-wasip2, x86_64-pc-windows-msvc, wasm64-unknown-unknown.