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
20 changes: 20 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,25 @@
# DevTesting Changelog

## 1.7.0: November 13, 2026

This release makes it possible to create stubs that return a placeholder value until they’re
configured, so that a test that calls an unconfigured stub fails instead of crashing.

- The new `DefaultStubValueProviding` protocol lets a type provide a default value for stubs that
return it. DevTesting conforms common standard library and Foundation types, including
`Array`, `Bool`, `Data`, `Date`, `Dictionary`, floating point and integer types, `Optional`,
`Set`, `String`, `URL`, and `UUID`.
- `Stub` has a new `init()` that returns the default stub value until configured, available when
its return type conforms to `DefaultStubValueProviding`.
- `ThrowingStub` has a new `init()` for stubs whose error type is `any Error`. It throws an
unspecified error until configured.
- The new `ArbitraryError` type is an error for tests that just need an error to throw.
`RandomValueGenerating` has a new `randomError(fileID:function:)` function that creates
one with a random description beginning with the calling file and function. If your tests
already extend `RandomValueGenerating` with a function named `randomError`, you may need to
rename or remove it to avoid ambiguous calls.


## 1.6.0: June 16, 2026

This release moves DevTesting’s seedable random number generator and random value generation
Expand Down
4 changes: 4 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,13 +11,17 @@ and DevRandom. The primary library for automated testing is DevTesting. It provi
- Case iterables
- Data
- Dates
- Errors
- Floating point types
- Integer types
- Optionals
- Strings
- UUIDs
- URLs, URL components, and URL query items
- `Stub` and `ThrowingStub`, which provide stubbing and spying functionality for your mocks.
Stubs whose return types conform to `DefaultStubValueProviding` can be created without
arguments, so that unconfigured stubs return placeholder values instead of crashing.
- `ArbitraryError`, an error type for tests that just need an error to throw.

DevRandom is a supporting library that includes the core random value generation code. It is used by
DevTesting, but can also be used in your application for random value generation.
Expand Down
2 changes: 2 additions & 0 deletions Sources/DevTesting/Documentation.docc/Documentation.md
Original file line number Diff line number Diff line change
Expand Up @@ -34,6 +34,8 @@ detailed information about how those dependencies were used.
- <doc:UsingStubs>
- ``Stub``
- ``ThrowingStub``
- ``DefaultStubValueProviding``
- ``ArbitraryError``

### Collection Generation Extensions

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,11 @@
- ``randomDate(in:)-(Range<Date>)``


### Errors

- ``randomError(fileID:function:)``


### Numeric Types

- ``randomFloat64(in:)-(Range<Float64>)``
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -361,7 +361,7 @@ types. For example:
}


mutating func randomError() -> MyAppError {
mutating func randomAppError() -> MyAppError {
return MyAppError(code: randomInt(in: 100 ..< 1000))
}

Expand Down
65 changes: 56 additions & 9 deletions Sources/DevTesting/Documentation.docc/UsingStubs.md
Original file line number Diff line number Diff line change
Expand Up @@ -112,22 +112,57 @@ This pattern is especially valuable when writing assertions about how your code
function, as you can easily access specific parameters from the recorded calls.


### Force unwrapping stub properties
### Default-initialized stub properties

Stub properties are declared as implicitly unwrapped optionals to fail fast when stubs are not set
up correctly. By using implicitly unwrapped optionals, failing to properly mock a required
dependency will crash immediately at test time, making it obvious what went wrong.
Where possible, initialize stub properties with a default stub, so that a test that calls a stub
it didn’t configure gets a value instead of crashing:

final class MockFileManager: FileManager {
var documentsDirectoryStub: Stub<Void, URL>!
// Returns URL.defaultStubValue until configured
var documentsDirectoryStub = Stub<Void, URL>()

// If this stub isn’t initialized and the property is accessed, the test will crash
// immediately with a clear error
var documentsDirectory: URL {
documentsDirectoryStub()
// Throws an unspecified error until configured
var loadContentStub = ThrowingStub<String, Data, any Error>()

…
}

A crash in an unconfigured stub can be hard to trace, especially when tests run in parallel, and it
ends the whole test run. A default value lets the test continue, and in most cases fail, without
taking other tests down with it.

`Stub()` is available when the stub’s return type conforms to ``DefaultStubValueProviding``.
DevTesting provides conformances for common standard library and Foundation types, using values
that are recognizable placeholders where possible, such as `1_234_567_890` and `"default stub"`.
Conform your own types by composing their properties’ defaults:

extension Person: DefaultStubValueProviding {
static var defaultStubValue: Person {
return Person(
givenName: .defaultStubValue,
familyName: .defaultStubValue,
age: .defaultStubValue,
)
}
}

A default value only keeps an unconfigured stub from crashing. It isn’t meant to be realistic, so
tests should still configure every stub whose return value they depend on. Similarly, a throwing
stub that throws `any Error` throws by default, so a test of a success path must configure it.


### Force unwrapping stub properties

When a stub’s return type has no default value, or the stub throws a specific error type, declare
the stub property as an implicitly unwrapped optional. Tests must configure these stubs before
they’re called, or the test crashes.

final class MockFileManager: FileManager {
var fileHandleStub: Stub<String, FileHandle>!

…
}


## Configuring Stub Behavior

Expand All @@ -154,6 +189,18 @@ For ``ThrowingStub``, you can configure default success or failure behavior:
// Always throw the same error
fileManager.loadContentStub = ThrowingStub(defaultResult: .failure(FileError.notFound))

When a test only needs _an_ error, rather than a specific one, use an ``ArbitraryError``. You can
create one with a description, or with
``RandomValueGenerating/randomError(fileID:function:)``, which gives it a random description
that begins with the calling file and function:

let error = randomError()
fileManager.loadContentStub = ThrowingStub(defaultError: error)

#expect(throws: error) {
try documentLoader.loadDocument(at: path)
}


### Result queues

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -183,6 +183,24 @@ extension RandomValueGenerating {
}


// MARK: - Errors

/// Returns an arbitrary error with a random description.
///
/// The description begins with the file ID and function that called this function, which makes it easier to tell
/// where an error came from when a test fails.
///
/// - Parameters:
/// - fileID: The file ID of the caller. Defaults to the caller’s file ID.
/// - function: The name of the calling function. Defaults to the caller’s function name.
public mutating func randomError(
fileID: StaticString = #fileID,
function: StaticString = #function,
) -> ArbitraryError {
return ArbitraryError(description: "\(fileID):\(function)_\(randomAlphanumericString())")
}


// MARK: - Numeric Types

/// Returns a random binary floating point of the specified type within the specified range.
Expand Down
36 changes: 36 additions & 0 deletions Sources/DevTesting/Stubbing/ArbitraryError.swift
Original file line number Diff line number Diff line change
@@ -0,0 +1,36 @@
//
// ArbitraryError.swift
// DevTesting
//
// Created by Prachi Gauriar on 11/13/26.
//

import Foundation

/// An error for use in tests, such as the error a stub throws.
///
/// Use an arbitrary error when a test needs an error whose only job is to be thrown and recognized, as in
///
/// let error = randomError()
/// mockFileManager.loadContentStub = ThrowingStub(defaultError: error)
///
/// #expect(throws: error) {
/// try documentLoader.loadDocument(at: path)
/// }
public struct ArbitraryError: Error, CustomDebugStringConvertible, Hashable, Sendable {
/// A description of the error.
public let description: String


/// Creates a new arbitrary error with the specified description.
///
/// - Parameter description: A description of the error.
public init(description: String) {
self.description = description
}


public var debugDescription: String {
return description
}
}
Loading
Loading