Swift-Spyable

The Swift-Spyable macro automatically generates unique variable names for tracking method calls, arguments, and return values in spy classes. It uses a two-mode approach to ensure uniqueness:

1. Non-Descriptive Mode (Default): Used when a method's signature is unique within its protocol. It combines the function name with capitalized parameter names.

   • Pattern: functionName + CapitalizedParameterFirstNames
   • Example: func display(text: String, name: String) $\rightarrow$ displayTextName

2. Descriptive Mode (Conflict Resolution): Automatically triggered if multiple methods share the same base prefix (polymorphism). It includes parameter types and the return type to ensure uniqueness.

   • Pattern: functionName + CapitalizedParameterFirstNamesWithTypes + SanitizedReturnType
   • Example: func display(text: String, name: String) -> String $\rightarrow$ displayTextStringNameStringString

This mechanism allows the spy to distinguish between overloaded methods (methods with the same name but different signatures) without manual configuration.

When generating variable names, Swift-Spyable applies specific rules to parameter names and types to ensure they are valid identifiers:

Parameter Name Rules

• First Parameter Names: Uses the external parameter name (e.g., func foo(external internal: String) uses external).
• Underscore Parameters: Completely ignored (e.g., func foo(_ text: String, name: String) $\rightarrow$ fooName).
• Capitalization: The first letter of each parameter name is capitalized.

Type Sanitization Rules

• Collection Conversion: Shorthand syntax is converted to descriptive names: [Type] $\rightarrow$ ArrayType and [Key: Value] $\rightarrow$ DictionaryKeyValue.
• Optional Handling: Trailing ? marks are converted to an Optional prefix (e.g., String? $\rightarrow$ OptionalString, String?? $\rightarrow$ OptionalOptionalString).
• Attribute Handling: Function attributes are converted to their non-attributed form (e.g., @escaping $\rightarrow$ escaping, @MainActor $\rightarrow$ MainActor).
• Forbidden Characters: The following are removed: :, [, ], <, >, (, ), ,, , -, &.

Spyable uses a Swift macro to automatically generate spy classes for your protocols. This is useful for testing, SwiftUI previews, or creating dummy implementations.

To use it:

1. Import the module: import Spyable.
2. Annotate your protocol with @Spyable.
3. The macro generates a class named [ProtocolName]Spy that conforms to your protocol and tracks all interactions.

The generated spy provides properties to inspect method calls, such as [methodName][paramName]CallsCount, [methodName][paramName]ReceivedArg, and [methodName][paramName]ReturnValue.

import Spyable

@Spyable
public protocol ServiceProtocol {
  var name: String { get }
  func fetchConfig(arg: UInt8) async throws -> [String: String]
}

// Usage in a test
func testFetchConfig() async throws {
  let serviceSpy = ServiceProtocolSpy()
  
  // Set a stubbed return value
  serviceSpy.fetchConfigArgReturnValue = ["key": "value"]

  // ... execute code under test ...

  // Verify interactions
  XCTAssertEqual(serviceSpy.fetchConfigArgCallsCount, 1)
  XCTAssertEqual(serviceSpy.fetchConfigArgReceivedInvocations, [1])
}

When working with complex Swift types, be aware of how the naming algorithm might produce unexpected results:

• Type Ambiguity: The algorithm does not distinguish between type aliases and actual types, nor does it handle module-qualified types (e.g., Swift.String vs String) differently.
• Generic Constraints: Constraints and where clauses are lost. func process<T: Codable>(item: T) becomes processItemTT.
• Protocol Composition: Composition is concatenated without separators (e.g., Codable & Hashable $\rightarrow$ CodableHashable).
• Unnamed Tuples: Elements without labels are simply concatenated (e.g., (Int, Int) $\rightarrow$ IntInt).
• Case Sensitivity: The algorithm is case-sensitive. func process(Data: String) and func process(data: String) will result in a naming conflict.
• Complex Function Types: Highly nested function types or complex generics may result in very long, hard-to-read variable names.

To test overloaded methods, use the generated unique property names to set up return values and verify calls for each specific signature independently.

func testPolymorphism() {
    let spy = DataProcessorSpy()
    
    // 1. Setup different return values for each overload
    spy.computeValueStringStringReturnValue = "String result"
    spy.computeValueIntStringReturnValue = "Int result"
    spy.computeValueBoolStringReturnValue = "Bool result"
    
    // 2. Call different overloads
    let stringResult = spy.compute(value: "test")
    let intResult = spy.compute(value: 42)
    let boolResult = spy.compute(value: true)
    
    // 3. Verify each overload was called exactly once
    XCTAssertEqual(spy.computeValueStringStringCallsCount, 1)
    XCTAssertEqual(spy.computeValueIntStringCallsCount, 1)
    XCTAssertEqual(spy.computeValueBoolStringCallsCount, 1)
    
    // 4. Verify correct arguments were captured
    XCTAssertEqual(spy.computeValueStringStringReceivedValue, "test")
    XCTAssertEqual(spy.computeValueIntStringReceivedValue, 42)
    XCTAssertEqual(spy.computeValueBoolStringReceivedValue, true)
}