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#

silk
pub const FILE: u8

A note of a file's contents, read through a provider rooted at the note's root.

ENTRY#

silk
pub const ENTRY: u8

A note of whether a path exists, and whether it is a file or a directory, and its size.

LISTING#

silk
pub const LISTING: u8

A note of the names in a directory.

VARIABLE#

silk
pub const VARIABLE: u8

A note of one environment variable, named by the note's path. Its root is empty.

WRITE#

silk
pub const WRITE: u8

A note of a change to a path: a write, a new file or directory, or a removal.

TEMPORARY#

silk
pub const TEMPORARY: u8

A note of a directory the test created with a unique name. Notes under it are the test's own.

CLOCK#

silk
pub const CLOCK: u64

The mark of a clock read.

RANDOM#

silk
pub const RANDOM: u64

The mark of a random number from the host.

NETWORK#

silk
pub const NETWORK: u64

The mark of a socket or a name lookup.

PROCESS#

silk
pub const PROCESS: u64

The mark of a child process.

OVERFLOW#

silk
pub const OVERFLOW: u64

The mark of a note that did not fit in the buffer.

ENVIRONMENT#

silk
pub const ENVIRONMENT: u64

The mark of a list of environment variable names.

HOST#

silk
pub const HOST: u64

The mark of a read of the host: its system information, standard input, signals or the program's arguments.

silk
pub const HEADER: usize

The size of a buffer's header, before its notes.

start#

silk
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#

silk
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#

silk
pub fn watching() -> bool

Whether a watch is active.

mark#

silk
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#

silk
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.

View the source of this page