Conform DecodingError to CustomStringConvertible and return a tidier description for debugging.

ZevEisenberg · ZevEisenberg · commit 4cd346f2c175 · 2025-04-21T09:36:58.000-04:00
diff --git a/stdlib/public/core/Codable.swift b/stdlib/public/core/Codable.swift
@@ -3724,6 +3724,60 @@ public enum DecodingError: Error {
   }
 }
 
+extension DecodingError: CustomStringConvertible {
+  public var description: String {
+    switch self {
+    case .typeMismatch(let expectedType, let context):
+      return "Type mismatch: expected \(expectedType) at \(context.codingPath.readable)"
+    case .valueNotFound(let expectedType, let context):
+      return "Expected to find value of type \(expectedType), but value was missing at \(context.codingPath.readable)"
+    case .keyNotFound(let codingKey, let context):
+      return "Key not found: expected '\(codingKey.compactDescription)' at \(context.codingPath.readable)"
+    case .dataCorrupted(let context):
+      // The codingPath is empty here, so we defer to the underlying error.
+      var output = "Data corrupted: \(context.debugDescription)"
+      if let underlyingError = context.underlyingError {
+        if !output.hasSuffix(".") {
+          output.append(".")
+        }
+        output.append(" Underlying error: \(underlyingError)")
+      }
+      return output
+    }
+  }
+}
+
+private extension [any CodingKey] {
+  var readable: String {
+    self
+      .map { $0.compactDescription }
+      .joined(separator: "/")
+  }
+}
+
+private extension CodingKey {
+  /// Represents a coding key as either its integer representation, if available
+  /// (in square brackets), or its string representation. If there is no integer
+  /// value, and the string value happens to represent an integer, wrap it in
+  /// double quotes to avoid ambiguity.
+  var compactDescription: String {
+    if let intValue {
+      "[" + String(intValue) + "]"
+    } else {
+      // If the string key looks like an int, put quotes around it so it's clear
+      // that it's actually a string. If it's not a numeric string, don't bother
+      // because it's not ambiguous.
+      if let intyString = Int(stringValue) {
+        """
+        "\(intyString)"
+        """
+      } else {
+        stringValue
+      }
+    }
+  }
+}
+
 // The following extensions allow for easier error construction.
 
 internal struct _GenericIndexKey: CodingKey, Sendable {
diff --git a/test/stdlib/CodableTests.swift b/test/stdlib/CodableTests.swift
@@ -1100,6 +1100,195 @@ class TestCodable : TestCodableSuper {
             expectRoundTripEqualityThroughPlist(for: UUIDCodingWrapper(uuid), lineNumber: testLine)
         }
     }
+
+    // MARK: - DecodingError
+    func expectErrorDescription<T: Decodable>(
+        _ expectedErrorDescription: String,
+        decoding _: T.Type,
+        fromJSON jsonString: String,
+        lineNumber: UInt = #line
+    ) {
+        let snakeCaseDecoder: JSONDecoder = {
+            let d = JSONDecoder()
+            d.keyDecodingStrategy = .convertFromSnakeCase
+            return d
+        }()
+
+        let jsonData = Data(jsonString.utf8)
+        do {
+            _ = try snakeCaseDecoder.decode(T.self, from: jsonData)
+        } catch let error as DecodingError {
+            expectEqual(String(describing: error), expectedErrorDescription, "Unexpectedly wrong error: \(error)", line: lineNumber)
+        } catch {
+            expectUnreachableCatch(error, ": Unexpected error type when decoding \(T.self)", line: lineNumber)
+        }
+    }
+
+    func test_decodingError_typeMismatch() {
+        expectErrorDescription(
+            "Type mismatch: expected String at [0]/address/city/birds/[1]/name",
+            decoding: [Person].self,
+            fromJSON: #"""
+                [
+                    {
+                        "first_name": "John",
+                        "last_name": "Appleseed",
+                        "address": {
+                            "street": "123 Main St",
+                            "city": {
+                                "name": "Cupertino",
+                                "birds": [
+                                    {
+                                        "name": "The Big One",
+                                        "feathers": "all"
+                                    },
+                                    {
+                                        "name": 123,
+                                        "feathers": "some"
+                                    }
+                                ]
+                            }
+                        }
+                    }
+                ]
+                """#
+        )
+    }
+
+    func test_decodingError_typeMismatch_stringKeysThatLookLikeNumbers() {
+        expectErrorDescription(
+            #"""
+            Type mismatch: expected String at [0]/"3"
+            """#,
+            decoding: [TopThreeThings].self,
+            fromJSON: #"""
+                [
+                    {
+                        "1": "Raindrops on roses",
+                        "2": "Whiskers on kittens",
+                        "3": 42.0
+                    }
+                ]
+                """#
+        )
+    }
+
+    func test_decodingError_valueNotFound_firstNameMissing() {
+        expectErrorDescription(
+            "Expected to find value of type String, but value was missing at [0]/firstName",
+            decoding: [Person].self,
+            fromJSON: #"""
+                [
+                    {
+                        "first_name": null,
+                        "last_name": "Appleseed",
+                        "address": {
+                            "street": "123 Main St",
+                            "city": {
+                                "name": "Cupertino",
+                                "birds": []
+                            }
+                        }
+                    }
+                ]
+                """#
+        )
+    }
+
+    func test_decodingError_valueNotFound_birdNameMissing() {
+        expectErrorDescription(
+            "Expected to find value of type String, but value was missing at [0]/address/city/birds/[1]/name",
+            decoding: [Person].self,
+            fromJSON: #"""
+                [
+                    {
+                        "first_name": "John",
+                        "last_name": "Appleseed",
+                        "address": {
+                            "street": "123 Main St",
+                            "city": {
+                                "name": "Cupertino",
+                                "birds": [
+                                    {
+                                        "name": "The Big One",
+                                        "feathers": "all"
+                                    },
+                                    {
+                                        "name": null,
+                                        "feathers": "some"
+                                    }
+                                ]
+                            }
+                        }
+                    }
+                ]
+                """#
+        )
+    }
+
+    func test_decodingError_valueNotFound_addressMissing() {
+        expectErrorDescription(
+            "Expected to find value of type Dictionary<String, Any>, but value was missing at [0]/address",
+            decoding: [Person].self,
+            fromJSON: #"""
+                [
+                    {
+                        "first_name": "John",
+                        "last_name": "Appleseed",
+                        "address": null
+                    }
+                ]
+                """#
+        )
+    }
+
+    func test_decodingError_keyNotFound() {
+        expectErrorDescription(
+            "Key not found: expected 'name' at [0]/address/city/birds/[1]",
+            decoding: [Person].self,
+            fromJSON: #"""
+                [
+                    {
+                        "first_name": "John",
+                        "last_name": "Appleseed",
+                        "address": {
+                            "street": "123 Main St",
+                            "city": {
+                                "name": "Cupertino",
+                                "birds": [
+                                    {
+                                        "name": "The Big One",
+                                        "feathers": "all"
+                                    },
+                                    {
+                                        "feathers": "some"
+                                    }
+                                ]
+                            }
+                        }
+                    }
+                ]
+                """#
+        )
+    }
+
+    func test_decodingError_dataCorrupted() {
+        expectErrorDescription(
+            #"""
+            Data corrupted: The given data was not valid JSON. Underlying error: Error Domain=NSCocoaErrorDomain Code=3840 "Unexpected character 'a' around line 5, column 10." UserInfo={NSJSONSerializationErrorIndex=81, NSDebugDescription=Unexpected character 'a' around line 5, column 10.}
+            """#,
+            decoding: [Person].self,
+            fromJSON: #"""
+                [
+                    {
+                        "first_name": "John",
+                        "last_name": "Appleseed",
+                        address
+                    }
+                ]
+                """#
+        )
+    }
 }
 
 // MARK: - Helper Types
@@ -1130,6 +1319,35 @@ struct TopLevelWrapper<T> : Codable, Equatable where T : Codable, T : Equatable
     }
 }
 
+struct Person: Decodable {
+    var firstName, lastName: String
+    var address: Address
+}
+
+struct Address: Decodable {
+    var street: String
+    var city: City
+}
+
+struct City: Decodable {
+    var name: String
+    var birds: [Bird]
+}
+
+struct Bird: Decodable {
+    var name, feathers: String
+}
+
+/// A struct whose encoded representation has string keys that consist only of numbers.
+struct TopThreeThings: Decodable {
+    var one, two, three: String
+    enum CodingKeys: String, CodingKey {
+        case one = "1"
+        case two = "2"
+        case three = "3"
+    }
+}
+
 // MARK: - Tests
 
 #if !FOUNDATION_XCTEST
@@ -1183,6 +1401,13 @@ var tests = [
     "test_URL_Plist" : TestCodable.test_URL_Plist,
     "test_UUID_JSON" : TestCodable.test_UUID_JSON,
     "test_UUID_Plist" : TestCodable.test_UUID_Plist,
+    "test_decodingError_typeMismatch": TestCodable.test_decodingError_typeMismatch,
+    "test_decodingError_typeMismatch_stringKeysThatLookLikeNumbers": TestCodable.test_decodingError_typeMismatch_stringKeysThatLookLikeNumbers,
+    "test_decodingError_valueNotFound_firstNameMissing": TestCodable.test_decodingError_valueNotFound_firstNameMissing,
+    "test_decodingError_valueNotFound_birdNameMissing": TestCodable.test_decodingError_valueNotFound_birdNameMissing,
+    "test_decodingError_valueNotFound_addressMissing": TestCodable.test_decodingError_valueNotFound_addressMissing,
+    "test_decodingError_keyNotFound": TestCodable.test_decodingError_keyNotFound,
+    "test_decodingError_dataCorrupted": TestCodable.test_decodingError_dataCorrupted,
 ]
 
 #if os(macOS)
