mirror of
https://github.com/apple/swift-log
synced 2026-11-22 03:40:39 +00:00
Add testing logs best practice (#475)
Add a Best Practice guide on how to test logging. ### Motivation: There are 2 recommended ways of propagating logs in components, both are testable. But there is no any kind of documentation on how to do it. ### Modifications: Add a "Testing code that logs" Best Practice guide. ### Result: Logs testing is now documented. --------- Co-authored-by: Joseph Heck <j_heck@apple.com>
This commit is contained in:
1 parent
c4e96785bf
commit
8a6b9eab84
2 files changed
+82
No files matched your search
@@ -0,0 +1,81 @@
|
||||
# 004: Testing code that logs
|
||||
|
||||
Validate what you code logs by capturing entries in memory rather than bootstrapping a process-wide backend.
|
||||
|
||||
## Overview
|
||||
|
||||
Import and use `InMemoryLogging`, which provides an `InMemoryLogHandler` that collects every emitted record into an array you can inspect.
|
||||
Keep a handler you create local to each test.
|
||||
Each handler that you create in a test has no shared state, so the test stays isolated is safe to run on parallel with other tests.
|
||||
Don't use ``LoggingSystem/bootstrap(_:)`` in a test, it sets one process-wide backend and traps if called twice.
|
||||
|
||||
Add the product to your test target:
|
||||
|
||||
```swift
|
||||
.product(name: "InMemoryLogging", package: "swift-log")
|
||||
```
|
||||
|
||||
### Capture logs from a logger you pass in
|
||||
|
||||
When the code under test accepts a `Logger` (see <doc:003-AcceptingLoggers>), back it with
|
||||
an `InMemoryLogHandler` and validate the results on `entries`.
|
||||
|
||||
The following code illustrates how to set up and validate a handler using `InMemoryLogging` to check the expected results:
|
||||
|
||||
```swift
|
||||
import InMemoryLogging
|
||||
import Logging
|
||||
import Testing
|
||||
|
||||
struct RequestProcessor {
|
||||
func handle(id: String, logger: Logger) {
|
||||
logger.info("request received", metadata: ["request.id": "\(id)"])
|
||||
}
|
||||
}
|
||||
|
||||
@Test
|
||||
func stampsRequestID() {
|
||||
let handler = InMemoryLogHandler()
|
||||
let logger = Logger(label: "test", factory: { _ in handler })
|
||||
|
||||
RequestProcessor().handle(id: "42", logger: logger)
|
||||
|
||||
#expect(handler.entries.count == 1)
|
||||
#expect(handler.entries[0].message == "request received")
|
||||
#expect(handler.entries[0].metadata["request.id"] == "42")
|
||||
}
|
||||
```
|
||||
|
||||
Each `Entry` is equatable and exposes `level`, `message`, `metadata`, and `error`.
|
||||
The handler log level defaults to ``Logger/Level/info``; set `handler.logLevel = .trace` before you use it to
|
||||
capture lower levels.
|
||||
|
||||
### Capture logs from code that reads `Logger.current`
|
||||
|
||||
When the code you want to test reads the task-local ``Logger/current`` instead of taking a parameter, bind an `InMemoryLogHandler` for the scope of that by using ``withLogger(logLevel:handler:metadata:_:)-2pd9p``.
|
||||
The handler shares its storage by reference, so the copy you hold sees what was logged.
|
||||
|
||||
Bind the handler for the scope of the call and validate the captured entry:
|
||||
|
||||
```swift
|
||||
import InMemoryLogging
|
||||
import Logging
|
||||
import Testing
|
||||
|
||||
struct AnalyticsClient {
|
||||
func track(_ event: String) {
|
||||
Logger.current.info("event", metadata: ["event.name": "\(event)"])
|
||||
}
|
||||
}
|
||||
|
||||
@Test
|
||||
func tracksEvent() {
|
||||
let handler = InMemoryLogHandler()
|
||||
withLogger(handler: handler) { _ in
|
||||
AnalyticsClient().track("signup") // calls Logger.current.info(...)
|
||||
}
|
||||
|
||||
#expect(handler.entries.count == 1)
|
||||
#expect(handler.entries[0].metadata["event.name"] == "signup")
|
||||
}
|
||||
```
|
||||
@@ -41,3 +41,4 @@ practice includes:
|
||||
- <doc:001-ChoosingLogLevels>
|
||||
- <doc:002-StructuredLogging>
|
||||
- <doc:003-AcceptingLoggers>
|
||||
- <doc:004-TestingLogging>
|
||||
Reference in new issue
Block a user