Mock

type Reader

Mock: deterministic stand-ins for the world outside the program: the filesystem, environment, and console. Networking mocks live under Mock.Net.

These are STATEFUL: Mock.FS.File(path, content) writes into a store the real FS.File then reads back, so a test can write and read again, and clear() undoes it. That state is global and lives until cleared, which is what makes hook ordering and write/read round trips testable, and also what makes two tests able to interfere.

When a test only needs canned ANSWERS, replacing the capability is the better tool: with FS.File = MyFake { ... } do ... end swaps the implementation for one lexical region, holds no global state, needs no clearing, and cannot leak into another test. See spec/capability_stdlib_fs.kex for the shape of a stand-in (kexhq/kex#143).

Opt-in on purpose (issue #144): this module used to ride along inside a prelude networking file, so importing the prelude made every Mock.* reachable from every program without anyone asking for it. Reachable is still not callable: the runtime denies the mock intrinsics outside spec files, the REPL, and --allow-mocks, but it should also not be in scope by accident. A qualified Mock.FS.File(...) auto-loads this file like any other opt-in module.

All Mock.* sub-modules live in a single module Mock block so merged compilation units never see duplicate top-level Mock modules. A stand-in's read hook: a path in, its content or None out.

type Lookup

An environment stand-in's lookup hook: a name in, its value or None out.

type Writer

An environment stand-in's WRITE hook: the name and the value a program set. A Mock.Env is an immutable record, so a write cannot land in its vars, and it must not reach the real environment, or a test would leak a variable into the next one and into anything the suite starts. The hook is how a test observes the write instead: record it, assert on it, or ignore it, which is what None does.

module Mock

record Files

A stand-in for the FS.File capability, for with FS.File = .... Unlike the Mock.* functions below it holds no global state, needs no clear(), and cannot leak past its block. What it cannot do is change: write then read back is not something a value does, so a test needing that round trip still wants Mock.FS (kexhq/kex#143).

with FS.File = Mock.Files { files: {"kex.toml": "name = \"demo\""} } do
  assert(loadConfig() == "demo")
end

onRead takes over when a test needs an ANSWER rather than a fixture: content derived from the path, a failure on the third call, a record of what was asked for. It is consulted first and its None means "no such file", so a callback can model absence too.

Fields

files

Map<FS.FilePath, String> optional

onRead

Reader? optional

Implements FS.File.

cannedRead(path)

read(path)

readBytes(path)

readLines(path)

feed(path)

size(path)

exists?(path)

file?(path)

directory?(path)

absolute(path)

open(path, mode)

write(path, content)

writeBytes(path, content)

append(path, content)

delete(path)

copy(src, dst)

rename(src, dst)

record Env

A stand-in for the ENV capability. A name simply left out of vars reads as unset, which is the whole reason Mock.ENV.unset exists: absence is an answer programs act on. onGet answers instead of the map when a test wants a rule rather than a fixture.

with ENV = Mock.Env { vars: {"HOME": "/fake"} } do
  assert(configHome() == "/fake/.config")
end

Fields

vars

Map<String, String> optional

onGet

Lookup? optional

onSet

Writer? optional

Implements ENV.

lookup(key)

get(key, default)

has?(key)

keys

values

count

each(f)

entries

set(name, value)

unset(name)

module Mock.FS

A stateful stand-in for the filesystem: files a test declares, that the real FS.File then reads back.

The store is global and lives until clear, which is what makes a write followed by a read testable, and what makes two tests able to interfere. Clear it in an after hook.

describe "the config loader" do
  before do
    Mock.FS.files({ "app.conf": "port = 8080\n" })
  end

  after do
    Mock.FS.clear()
  end

  it "reads the port" do
    Assert.equal(loadPort(), 8080)
  end
end

File(path: FS.FilePath, content: String) -> Void

Mock.FS.File("app.conf", "port = 8080\n")

Directory(path: FS.FilePath) -> Void

Mock.FS.Directory("src")

clear : Void

after do
  Mock.FS.clear()
end

files(entries: Map<FS.FilePath, String>) -> Void

Mock.FS.files({
  "app.conf": "port = 8080\n",
  "hosts":    "localhost\n"
})

onRead(reader: Reader) -> Void

Mock.FS.onRead do |path|
  path.endsWith?(".txt") then Just("stub") else None
end

module Mock.ENV

Overlays the process environment, so a test can say what ENV holds instead of depending on how it was launched.

The overlay is global and lives until clear: clear it in an after hook.

Mock.ENV.vars({ "HOME": "/fake", "LOG_LEVEL": "debug" })
assert(configPath() == "/fake/.config")
Mock.ENV.clear()

set(name: String, value: String) -> Void

Mock.ENV.set("LOG_LEVEL", "debug")

unset(name: String) -> Void

Mock.ENV.unset("HOME")
Assert.equal(configPath(), ".")

clear : Void

after do
  Mock.ENV.clear()
end

vars(entries: Map<String, String>) -> Void

Mock.ENV.vars({ "HOME": "/fake", "LOG_LEVEL": "debug" })

module Mock.IO

A stateful stand-in for the console: captures what a program prints, and feeds it lines as if they had been typed.

The way to test a program that talks to a person without one being there.

Mock.IO.start()
Mock.IO.input("Ada", "42")
greet()
Assert.equal(Mock.IO.output(), "hello, Ada\n")
Mock.IO.stop()

start : Void

before do
  Mock.IO.start()
end

stop : Void

after do
  Mock.IO.stop()
end

output : String

Mock.IO.start()
IO.printLine("hello")
Assert.equal(Mock.IO.output(), "hello\n")

clear : Void

setUpNoisily()
Mock.IO.clear()
theThingUnderTest()
Assert.equal(Mock.IO.output(), "done\n")

input(first, second, third, fourth) -> Void

Mock.IO.input(["Ada", "42"])

Mock.IO.input("Ada", "42")

module Mock.Net

Scriptable networking values are namespaced so importing Mock does not recreate any of the removed global HTTP types.

module Mock.Net.HTTP

Canned HTTP transport state for networking specifications.

record Transport

Responses returned in order by a scripted transport.

Fields

responses

[Any]

module Mock.Net.DNS

Canned DNS resolver state for networking specifications.

record ResolverScript

Hostname-to-address answers supplied without touching the network.

Fields

answers

{String: [String]}

module Mock.Net.Socket

Canned byte-stream state for socket specifications.

record Script

Binary chunks delivered in order as incoming socket data.

Fields

incoming

[Binary]

module Mock.Net.WebSocket

Canned message state for WebSocket specifications.

record Script

High-level messages delivered in order by a scripted connection.

Fields

incoming

[Any]