From 9e24b26aa24845d30c6323587224a6307960c25e Mon Sep 17 00:00:00 2001 From: Prachi Gauriar Date: Fri, 13 Nov 2026 22:56:56 -0500 Subject: [PATCH] Add ArbitraryError and support for default stub values MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Add the DefaultStubValueProviding protocol, which lets a type provide a default value for stubs that return it. Conform common standard library and Foundation types, using recognizable placeholder values where possible. - Add Stub.init(), which returns the default stub value until the stub is configured, for return types that conform to DefaultStubValueProviding. - Add ThrowingStub.init() for stubs whose error type is any Error. It throws an unspecified error until the stub is configured. - Add ArbitraryError, an error type for tests that just need an error to throw, and a randomError function on RandomValueGenerating that creates one with a random description beginning with the calling file and function. - Rewrite the guidance on stub properties in Using Stubs to recommend default-initialized stubs, and document ArbitraryError. - Rename the randomError example in Using Random Value Generation so it doesn’t collide with the new function. - Mention the new types in the README and add a 1.7.0 changelog entry. --- CHANGELOG.md | 20 ++ README.md | 4 + .../Documentation.docc/Documentation.md | 2 + .../RandomValueGenerating.md | 5 + .../UsingRandomValueGeneration.md | 2 +- .../Documentation.docc/UsingStubs.md | 65 +++++- .../RandomValueGenerating.swift | 18 ++ .../DevTesting/Stubbing/ArbitraryError.swift | 36 +++ .../Stubbing/DefaultStubValueProviding.swift | 216 ++++++++++++++++++ .../ThrowingStub+DefaultStubValue.swift | 30 +++ .../RandomValueGeneratingTests.swift | 17 ++ .../Stubbing/ArbitraryErrorTests.swift | 20 ++ .../DefaultStubValueProvidingTests.swift | 64 ++++++ .../ThrowingStub+DefaultStubValueTests.swift | 70 ++++++ 14 files changed, 559 insertions(+), 10 deletions(-) create mode 100644 Sources/DevTesting/Stubbing/ArbitraryError.swift create mode 100644 Sources/DevTesting/Stubbing/DefaultStubValueProviding.swift create mode 100644 Sources/DevTesting/Stubbing/ThrowingStub+DefaultStubValue.swift create mode 100644 Tests/DevTestingTests/Stubbing/ArbitraryErrorTests.swift create mode 100644 Tests/DevTestingTests/Stubbing/DefaultStubValueProvidingTests.swift create mode 100644 Tests/DevTestingTests/Stubbing/ThrowingStub+DefaultStubValueTests.swift diff --git a/CHANGELOG.md b/CHANGELOG.md index 1715089..4a7c2f3 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -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 diff --git a/README.md b/README.md index 4418481..e822ff9 100644 --- a/README.md +++ b/README.md @@ -11,6 +11,7 @@ and DevRandom. The primary library for automated testing is DevTesting. It provi - Case iterables - Data - Dates + - Errors - Floating point types - Integer types - Optionals @@ -18,6 +19,9 @@ and DevRandom. The primary library for automated testing is DevTesting. It provi - 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. diff --git a/Sources/DevTesting/Documentation.docc/Documentation.md b/Sources/DevTesting/Documentation.docc/Documentation.md index 9b23f9f..7ca2572 100644 --- a/Sources/DevTesting/Documentation.docc/Documentation.md +++ b/Sources/DevTesting/Documentation.docc/Documentation.md @@ -34,6 +34,8 @@ detailed information about how those dependencies were used. - - ``Stub`` - ``ThrowingStub`` +- ``DefaultStubValueProviding`` +- ``ArbitraryError`` ### Collection Generation Extensions diff --git a/Sources/DevTesting/Documentation.docc/RandomValueGenerating.md b/Sources/DevTesting/Documentation.docc/RandomValueGenerating.md index 59f8fdc..42c1cfb 100644 --- a/Sources/DevTesting/Documentation.docc/RandomValueGenerating.md +++ b/Sources/DevTesting/Documentation.docc/RandomValueGenerating.md @@ -22,6 +22,11 @@ - ``randomDate(in:)-(Range)`` +### Errors + +- ``randomError(fileID:function:)`` + + ### Numeric Types - ``randomFloat64(in:)-(Range)`` diff --git a/Sources/DevTesting/Documentation.docc/UsingRandomValueGeneration.md b/Sources/DevTesting/Documentation.docc/UsingRandomValueGeneration.md index b6e79a9..3678105 100644 --- a/Sources/DevTesting/Documentation.docc/UsingRandomValueGeneration.md +++ b/Sources/DevTesting/Documentation.docc/UsingRandomValueGeneration.md @@ -361,7 +361,7 @@ types. For example: } - mutating func randomError() -> MyAppError { + mutating func randomAppError() -> MyAppError { return MyAppError(code: randomInt(in: 100 ..< 1000)) } diff --git a/Sources/DevTesting/Documentation.docc/UsingStubs.md b/Sources/DevTesting/Documentation.docc/UsingStubs.md index bf0ef1d..7b266fa 100644 --- a/Sources/DevTesting/Documentation.docc/UsingStubs.md +++ b/Sources/DevTesting/Documentation.docc/UsingStubs.md @@ -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! + // Returns URL.defaultStubValue until configured + var documentsDirectoryStub = Stub() - // 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() + + … + } + +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! + + … + } + ## Configuring Stub Behavior @@ -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 diff --git a/Sources/DevTesting/Random Value Generation/RandomValueGenerating.swift b/Sources/DevTesting/Random Value Generation/RandomValueGenerating.swift index d69af58..7b5b169 100644 --- a/Sources/DevTesting/Random Value Generation/RandomValueGenerating.swift +++ b/Sources/DevTesting/Random Value Generation/RandomValueGenerating.swift @@ -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. diff --git a/Sources/DevTesting/Stubbing/ArbitraryError.swift b/Sources/DevTesting/Stubbing/ArbitraryError.swift new file mode 100644 index 0000000..756b081 --- /dev/null +++ b/Sources/DevTesting/Stubbing/ArbitraryError.swift @@ -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 + } +} diff --git a/Sources/DevTesting/Stubbing/DefaultStubValueProviding.swift b/Sources/DevTesting/Stubbing/DefaultStubValueProviding.swift new file mode 100644 index 0000000..c95d18f --- /dev/null +++ b/Sources/DevTesting/Stubbing/DefaultStubValueProviding.swift @@ -0,0 +1,216 @@ +// +// DefaultStubValueProviding.swift +// DevTesting +// +// Created by Prachi Gauriar on 11/13/26. +// + +import Foundation + +/// A type that can provide a default value for use as a stub’s unconfigured return value. +/// +/// Stubs whose return type conforms to this protocol can be created with no arguments, as in +/// `Stub()`. Such a stub returns its return type’s default stub value until it is configured, so a +/// test that calls an unconfigured stub gets a value instead of crashing on a force-unwrapped `nil`. +/// +/// Where possible, choose a default value that is obviously a placeholder rather than realistic data, so that it is +/// easy to recognize when debugging and unlikely to make a test pass by accident. Complex types can compose their +/// default from their properties’ defaults: +/// +/// extension Person: DefaultStubValueProviding { +/// public static var defaultStubValue: Person { +/// return Person( +/// givenName: .defaultStubValue, +/// familyName: .defaultStubValue, +/// age: .defaultStubValue, +/// ) +/// } +/// } +public protocol DefaultStubValueProviding { + /// The value a stub returns before it is configured. + static var defaultStubValue: Self { get } +} + + +extension Array: DefaultStubValueProviding { + /// An empty array. + public static var defaultStubValue: [Element] { + return [] + } +} + + +extension Bool: DefaultStubValueProviding { + /// `false`. + public static var defaultStubValue: Bool { + return false + } +} + + +extension CGFloat: DefaultStubValueProviding { + /// 1.234567890. + public static var defaultStubValue: CGFloat { + return 1.234567890 + } +} + + +extension Data: DefaultStubValueProviding { + /// The bytes `DE AD C0 DE`. + public static var defaultStubValue: Data { + return Data([0xDE, 0xAD, 0xC0, 0xDE]) + } +} + + +extension Date: DefaultStubValueProviding { + /// `Date.distantPast`. + public static var defaultStubValue: Date { + return .distantPast + } +} + + +extension Dictionary: DefaultStubValueProviding { + /// An empty dictionary. + public static var defaultStubValue: [Key: Value] { + return [:] + } +} + + +extension Float32: DefaultStubValueProviding { + /// 1.234567890. + public static var defaultStubValue: Float32 { + return 1.234567890 + } +} + + +extension Float64: DefaultStubValueProviding { + /// 1.234567890. + public static var defaultStubValue: Float64 { + return 1.234567890 + } +} + + +extension Int: DefaultStubValueProviding { + /// 1,234,567,890. + public static var defaultStubValue: Int { + return 1_234_567_890 + } +} + + +extension Int8: DefaultStubValueProviding { + /// 123. + public static var defaultStubValue: Int8 { + return 123 + } +} + + +extension Int16: DefaultStubValueProviding { + /// 12,345. + public static var defaultStubValue: Int16 { + return 12_345 + } +} + + +extension Int32: DefaultStubValueProviding { + /// 1,234,567,890. + public static var defaultStubValue: Int32 { + return 1_234_567_890 + } +} + + +extension Int64: DefaultStubValueProviding { + /// 1,234,567,890. + public static var defaultStubValue: Int64 { + return 1_234_567_890 + } +} + + +extension Optional: DefaultStubValueProviding { + /// `nil`. + public static var defaultStubValue: Wrapped? { + return nil + } +} + + +extension Set: DefaultStubValueProviding { + /// An empty set. + public static var defaultStubValue: Set { + return [] + } +} + + +extension String: DefaultStubValueProviding { + /// `"default stub"`. + public static var defaultStubValue: String { + return "default stub" + } +} + + +extension UInt: DefaultStubValueProviding { + /// 1,234,567,890. + public static var defaultStubValue: UInt { + return 1_234_567_890 + } +} + + +extension UInt8: DefaultStubValueProviding { + /// 123. + public static var defaultStubValue: UInt8 { + return 123 + } +} + + +extension UInt16: DefaultStubValueProviding { + /// 12,345. + public static var defaultStubValue: UInt16 { + return 12_345 + } +} + + +extension UInt32: DefaultStubValueProviding { + /// 1,234,567,890. + public static var defaultStubValue: UInt32 { + return 1_234_567_890 + } +} + + +extension UInt64: DefaultStubValueProviding { + /// 1,234,567,890. + public static var defaultStubValue: UInt64 { + return 1_234_567_890 + } +} + + +extension URL: DefaultStubValueProviding { + /// `https://default.stub`. + public static var defaultStubValue: URL { + return URL(string: "https://default.stub")! + } +} + + +extension UUID: DefaultStubValueProviding { + /// `DEADC0DE-DEAD-C0DE-DEAD-C0DEDEADC0DE`. + public static var defaultStubValue: UUID { + return UUID(uuidString: "DEADC0DE-DEAD-C0DE-DEAD-C0DEDEADC0DE")! + } +} diff --git a/Sources/DevTesting/Stubbing/ThrowingStub+DefaultStubValue.swift b/Sources/DevTesting/Stubbing/ThrowingStub+DefaultStubValue.swift new file mode 100644 index 0000000..eab8bcb --- /dev/null +++ b/Sources/DevTesting/Stubbing/ThrowingStub+DefaultStubValue.swift @@ -0,0 +1,30 @@ +// +// ThrowingStub+DefaultStubValue.swift +// DevTesting +// +// Created by Prachi Gauriar on 11/13/26. +// + +import Foundation + +extension ThrowingStub where ErrorType == Never, ReturnType: DefaultStubValueProviding { + /// Creates a new stub that returns `ReturnType.defaultStubValue` until it is configured. + public convenience init() { + self.init(defaultReturnValue: .defaultStubValue) + } +} + + +extension ThrowingStub where ErrorType == any Error { + /// The error that an unconfigured throwing stub throws. + private struct DefaultStubError: Error {} + + + /// Creates a new throwing stub that throws an error until it is configured. + /// + /// The error is deliberately unspecified. A test that needs a stub to throw a particular error should configure it + /// with that error. + public convenience init() { + self.init(defaultError: DefaultStubError()) + } +} diff --git a/Tests/DevTestingTests/Random Value Generation/RandomValueGeneratingTests.swift b/Tests/DevTestingTests/Random Value Generation/RandomValueGeneratingTests.swift index b7338e6..59472d7 100644 --- a/Tests/DevTestingTests/Random Value Generation/RandomValueGeneratingTests.swift +++ b/Tests/DevTestingTests/Random Value Generation/RandomValueGeneratingTests.swift @@ -119,6 +119,23 @@ struct RandomValueGeneratingTests { } + @Test + mutating func randomErrorUsesRandomNumberGenerator() { + for _ in iterationRange { + let error = generator.randomError(fileID: "Module/File.swift", function: "function()") + let expectedSuffix = String.randomAlphanumeric(count: Int.random(in: 5 ... 10, using: &rng), using: &rng) + #expect(error.description == "Module/File.swift:function()_\(expectedSuffix)") + } + } + + + @Test + mutating func randomErrorUsesCallerByDefault() { + let error = generator.randomError() + #expect(error.description.hasPrefix("DevTestingTests/RandomValueGeneratingTests.swift:\(#function)_")) + } + + @Test mutating func randomFloatUsesRandomNumberGenerator_halfOpenRange() { for _ in iterationRange { diff --git a/Tests/DevTestingTests/Stubbing/ArbitraryErrorTests.swift b/Tests/DevTestingTests/Stubbing/ArbitraryErrorTests.swift new file mode 100644 index 0000000..4139b38 --- /dev/null +++ b/Tests/DevTestingTests/Stubbing/ArbitraryErrorTests.swift @@ -0,0 +1,20 @@ +// +// ArbitraryErrorTests.swift +// DevTesting +// +// Created by Prachi Gauriar on 11/13/26. +// + +import DevTesting +import Foundation +import Testing + +struct ArbitraryErrorTests { + @Test + func initSetsDescription() { + let error = ArbitraryError(description: "description") + + #expect(error.description == "description") + #expect(error.debugDescription == "description") + } +} diff --git a/Tests/DevTestingTests/Stubbing/DefaultStubValueProvidingTests.swift b/Tests/DevTestingTests/Stubbing/DefaultStubValueProvidingTests.swift new file mode 100644 index 0000000..0e33456 --- /dev/null +++ b/Tests/DevTestingTests/Stubbing/DefaultStubValueProvidingTests.swift @@ -0,0 +1,64 @@ +// +// DefaultStubValueProvidingTests.swift +// DevTesting +// +// Created by Prachi Gauriar on 11/13/26. +// + +import DevTesting +import Foundation +import Testing + +struct DefaultStubValueProvidingTests { + @Test + func collectionDefaultsAreEmpty() { + #expect([Int].defaultStubValue.isEmpty) + #expect([String: Int].defaultStubValue.isEmpty) + #expect(Set.defaultStubValue.isEmpty) + } + + + @Test + func boolDefaultIsFalse() { + #expect(!Bool.defaultStubValue) + } + + + @Test + func optionalDefaultIsNil() { + #expect(Int?.defaultStubValue == nil) + } + + + @Test + func floatingPointDefaults() { + #expect(CGFloat.defaultStubValue == 1.234567890) + #expect(Float32.defaultStubValue == 1.234567890) + #expect(Float64.defaultStubValue == 1.234567890) + } + + + @Test + func integerDefaults() { + #expect(Int.defaultStubValue == 1_234_567_890) + #expect(Int8.defaultStubValue == 123) + #expect(Int16.defaultStubValue == 12_345) + #expect(Int32.defaultStubValue == 1_234_567_890) + #expect(Int64.defaultStubValue == 1_234_567_890) + #expect(UInt.defaultStubValue == 1_234_567_890) + #expect(UInt8.defaultStubValue == 123) + #expect(UInt16.defaultStubValue == 12_345) + #expect(UInt32.defaultStubValue == 1_234_567_890) + #expect(UInt64.defaultStubValue == 1_234_567_890) + } + + + @Test + func foundationDefaults() { + #expect(Data.defaultStubValue == Data([0xDE, 0xAD, 0xC0, 0xDE])) + #expect(Date.defaultStubValue == .distantPast) + #expect(String.defaultStubValue == "default stub") + #expect(URL.defaultStubValue == URL(string: "https://default.stub")) + #expect(UUID.defaultStubValue == UUID(uuidString: "DEADC0DE-DEAD-C0DE-DEAD-C0DEDEADC0DE")) + } +} diff --git a/Tests/DevTestingTests/Stubbing/ThrowingStub+DefaultStubValueTests.swift b/Tests/DevTestingTests/Stubbing/ThrowingStub+DefaultStubValueTests.swift new file mode 100644 index 0000000..e09d8d1 --- /dev/null +++ b/Tests/DevTestingTests/Stubbing/ThrowingStub+DefaultStubValueTests.swift @@ -0,0 +1,70 @@ +// +// ThrowingStub+DefaultStubValueTests.swift +// DevTesting +// +// Created by Prachi Gauriar on 11/13/26. +// + +import DevTesting +import Foundation +import Testing + +struct ThrowingStub_DefaultStubValueTests { + @Test + func stubInitReturnsDefaultStubValue() { + let stub = Stub() + + #expect(stub.defaultReturnValue == Int.defaultStubValue) + #expect(stub.returnValueQueue.isEmpty) + #expect(stub.calls.isEmpty) + + #expect(stub("argument") == Int.defaultStubValue) + #expect(stub.callArguments == ["argument"]) + } + + + @Test + func stubInitReturnsConfiguredValueAfterConfiguration() { + let stub = Stub() + stub.defaultResult = .success("configured") + + #expect(stub() == "configured") + } + + + @Test + func throwingStubInitThrowsUntilConfigured() throws { + let stub = ThrowingStub() + + #expect(stub.resultQueue.isEmpty) + #expect(stub.calls.isEmpty) + + #expect(throws: (any Error).self) { + try stub("argument") + } + #expect(stub.callArguments == ["argument"]) + + stub.defaultResult = .success(3) + #expect(try stub("argument") == 3) + } + + + @Test + func throwingStubInitWithVoidReturnTypeThrowsUntilConfigured() { + let stub = ThrowingStub() + + #expect(throws: (any Error).self) { + try stub() + } + } + + + @Test + func voidStubInitStillReturnsVoid() { + // Void can’t conform to DefaultStubValueProviding, so this must use the existing Void initializer + let stub = Stub() + + stub() + #expect(stub.calls.count == 1) + } +}