Add facade request configuration tests

Expose internal request builders for summaries, recommendations, history, and API test endpoints, and add unit tests that validate their configuration without network calls.

Author: rudrankriyam

Sources/MusadoraKit/History/MHistory+RecentlyPlayed.swift

@@ -12,16 +12,14 @@ public extension MHistory {
   static func recentlyPlayed(limit: Int? = nil) async throws -> MusicItemCollection<
     RecentlyPlayedMusicItem
   > {
-    var request = MusicRecentlyPlayedContainerRequest()
-    request.limit = limit
+    let request = recentlyPlayedContainerRequest(limit: limit)
     let response = try await request.response()
     return try await response.items.collectingAll(upTo: limit)
   }
 
   @available(iOS 16.0, macOS 13.0, tvOS 16.0, watchOS 9.0, *)
   static func recentlyPlayedSongs(limit: Int? = nil) async throws -> Songs {
-    var request = MusicRecentlyPlayedRequest<Song>()
-    request.limit = limit
+    let request = recentlyPlayedSongsRequest(limit: limit)
     let response = try await request.response()
     return response.items
   }
@@ -43,11 +41,34 @@ public extension MHistory {
   ///  ```
   @available(iOS 16.0, tvOS 16.0, watchOS 9.0, *, macOS 14.0, macCatalyst 17.0, *)
   static func mostPlayedSongs(limit: Int = 100) async throws -> Songs {
+    let request = mostPlayedSongsRequest(limit: limit)
+    let response = try await request.response()
+    return try await response.items.collectingAll(upTo: limit)
+  }
+}
+
+@available(iOS 16.0, macOS 13.0, tvOS 16.0, watchOS 9.0, *)
+extension MHistory {
+  internal static func recentlyPlayedContainerRequest(limit: Int?) -> MusicRecentlyPlayedContainerRequest {
+    var request = MusicRecentlyPlayedContainerRequest()
+    request.limit = limit
+    return request
+  }
+
+  internal static func recentlyPlayedSongsRequest(limit: Int?) -> MusicRecentlyPlayedRequest<Song> {
+    var request = MusicRecentlyPlayedRequest<Song>()
+    request.limit = limit
+    return request
+  }
+}
+
+@available(iOS 16.0, tvOS 16.0, watchOS 9.0, *, macOS 14.0, macCatalyst 17.0, *)
+extension MHistory {
+  internal static func mostPlayedSongsRequest(limit: Int) -> MusicLibraryRequest<Song> {
     var request = MusicLibraryRequest<Song>()
     request.limit = limit
     request.sort(by: \.playCount, ascending: false)
-    let response = try await request.response()
-    return try await response.items.collectingAll(upTo: limit)
+    return request
   }
 }
 

Sources/MusadoraKit/MusadoraKit.swift

@@ -58,12 +58,7 @@ extension MusadoraKit {
     /// }
     /// ```
     public static func test() async throws {
-        var components = AppleMusicURLComponents()
-        components.path = "test"
-
-        guard let url = components.url else {
-            throw URLError(.badURL)
-        }
+        let url = try testEndpointURL()
 
         let urlRequest = URLRequest(url: url)
         let request = MusicDataRequest(urlRequest: urlRequest)
@@ -89,4 +84,15 @@ extension MusadoraKit {
             throw error
         }
     }
+
+    internal static func testEndpointURL(components: MusicURLComponents = AppleMusicURLComponents()) throws -> URL {
+        var components = components
+        components.path = "test"
+
+        guard let url = components.url else {
+            throw URLError(.badURL)
+        }
+
+        return url
+    }
 }

Sources/MusadoraKit/MusicSummaries/MSummary+Replay.swift

@@ -24,7 +24,13 @@ public extension MSummary {
     include: [String]? = nil,
     extend: [String]? = nil
   ) async throws -> MusicSummaryResponse {
-    try await response(for: .latestYear, views: views, languageTag: languageTag, include: include, extend: extend)
+    let request = requestForLatest(
+      views: views,
+      languageTag: languageTag,
+      include: include,
+      extend: extend
+    )
+    return try await request.response()
   }
 
   /// Fetch the user's latest monthly Replay summary (previous calendar month).
@@ -45,17 +51,15 @@ public extension MSummary {
     now: Date = .now,
     timeZone: TimeZone = TimeZone(secondsFromGMT: 0) ?? .current
   ) async throws -> MusicSummaryResponse {
-    guard let period = MusicSummaryPeriod.latestMonth(calendar: calendar, now: now, timeZone: timeZone) else {
-      throw MusadoraKitError.invalidSummaryPeriod
-    }
-
-    return try await response(
-      for: period,
+    let context = LatestMonthContext(calendar: calendar, now: now, timeZone: timeZone)
+    let request = try requestForLatestMonth(
       views: views,
       languageTag: languageTag,
       include: include,
-      extend: extend
+      extend: extend,
+      context: context
     )
+    return try await request.response()
   }
 
   /// Fetch the user's latest Replay top artists for the most recent eligible year.
@@ -161,20 +165,92 @@ public extension MSummary {
   }
 }
 
-private extension MSummary {
-  static func response(
+extension MSummary {
+  internal struct LatestMonthContext {
+    let calendar: Calendar
+    let now: Date
+    let timeZone: TimeZone
+
+    init(
+      calendar: Calendar = .init(identifier: .gregorian),
+      now: Date = .now,
+      timeZone: TimeZone = TimeZone(secondsFromGMT: 0) ?? .current
+    ) {
+      self.calendar = calendar
+      self.now = now
+      self.timeZone = timeZone
+    }
+  }
+
+  internal static func requestForLatest(
+    views: Set<MusicSummaryView>,
+    languageTag: String?,
+    include: [String]?,
+    extend: [String]?
+  ) -> MusicSummaryRequest {
+    makeRequest(
+      period: .latestYear,
+      views: views,
+      languageTag: languageTag,
+      include: include,
+      extend: extend
+    )
+  }
+
+  internal static func requestForLatestMonth(
+    views: Set<MusicSummaryView>,
+    languageTag: String?,
+    include: [String]?,
+    extend: [String]?,
+    context: LatestMonthContext
+  ) throws -> MusicSummaryRequest {
+    guard let period = MusicSummaryPeriod.latestMonth(
+      calendar: context.calendar,
+      now: context.now,
+      timeZone: context.timeZone
+    ) else {
+      throw MusadoraKitError.invalidSummaryPeriod
+    }
+
+    return makeRequest(
+      period: period,
+      views: views,
+      languageTag: languageTag,
+      include: include,
+      extend: extend
+    )
+  }
+
+  private static func response(
     for period: MusicSummaryPeriod,
     views: Set<MusicSummaryView>,
     languageTag: String?,
     include: [String]? = nil,
     extend: [String]? = nil
   ) async throws -> MusicSummaryResponse {
+    let request = makeRequest(
+      period: period,
+      views: views,
+      languageTag: languageTag,
+      include: include,
+      extend: extend
+    )
+    return try await request.response()
+  }
+
+  internal static func makeRequest(
+    period: MusicSummaryPeriod,
+    views: Set<MusicSummaryView>,
+    languageTag: String?,
+    include: [String]? = nil,
+    extend: [String]? = nil
+  ) -> MusicSummaryRequest {
     var request = MusicSummaryRequest()
     request.period = period
     request.views = views
     request.languageTag = languageTag
     request.include = include
     request.extend = extend
-    return try await request.response()
+    return request
   }
 }

Sources/MusadoraKit/Recommendations/MRecommendation+personal.swift

@@ -92,9 +92,14 @@ public extension MRecommendation {
 @available(iOS 16.0, macOS 13.0, tvOS 16.0, watchOS 9.0, visionOS 1.0, *)
 extension MRecommendation {
   private static func personalRecommendations(_ limit: Int? = nil) async throws -> PersonalRecommendations {
-    var request = MusicPersonalRecommendationsRequest()
-    request.limit = limit
+    let request = personalRecommendationsRequest(limit: limit)
     let response = try await request.response()
     return try await response.recommendations.collectingAll(upTo: limit)
   }
+
+  internal static func personalRecommendationsRequest(limit: Int?) -> MusicPersonalRecommendationsRequest {
+    var request = MusicPersonalRecommendationsRequest()
+    request.limit = limit
+    return request
+  }
 }

Tests/MusadoraKitTests/History/MHistoryRecentlyPlayedRequestTests.swift

@@ -0,0 +1,27 @@
+@testable import MusadoraKit
+import MusicKit
+import Testing
+
+@Suite
+struct MHistoryRecentlyPlayedRequestTests {
+  @available(iOS 16.0, macOS 13.0, tvOS 16.0, watchOS 9.0, *)
+  @Test
+  func recentlyPlayedContainerRequestSetsLimit() {
+    let request = MHistory.recentlyPlayedContainerRequest(limit: 25)
+    #expect(request.limit == 25)
+  }
+
+  @available(iOS 16.0, macOS 13.0, tvOS 16.0, watchOS 9.0, *)
+  @Test
+  func recentlyPlayedSongsRequestSetsLimit() {
+    let request = MHistory.recentlyPlayedSongsRequest(limit: 10)
+    #expect(request.limit == 10)
+  }
+
+  @available(iOS 16.0, tvOS 16.0, watchOS 9.0, macOS 14.0, macCatalyst 17.0, *)
+  @Test
+  func mostPlayedSongsRequestSetsLimit() {
+    let request = MHistory.mostPlayedSongsRequest(limit: 100)
+    #expect(request.limit == 100)
+  }
+}

Tests/MusadoraKitTests/MusadoraKitTestEndpointTests.swift

@@ -0,0 +1,30 @@
+import Foundation
+@testable import MusadoraKit
+import Testing
+
+private struct BadURLMusicComponents: MusicURLComponents {
+  var queryItems: [URLQueryItem]?
+  var path: String = ""
+
+  var url: URL? {
+    nil
+  }
+}
+
+@Suite
+struct MusadoraKitTestEndpointTests {
+  @Test
+  func testEndpointURLBuilds() throws {
+    let url = try MusadoraKit.testEndpointURL()
+    expectEndpoint(url, equals: "https://api.music.apple.com/v1/test")
+  }
+
+  @Test
+  func testEndpointURLWithBadComponentsThrows() throws {
+    let error = #expect(throws: URLError.self) {
+      try MusadoraKit.testEndpointURL(components: BadURLMusicComponents())
+    }
+
+    #expect(error == URLError(.badURL))
+  }
+}

Tests/MusadoraKitTests/Recommendation/MRecommendationPersonalTests.swift

@@ -0,0 +1,18 @@
+@testable import MusadoraKit
+import MusicKit
+import Testing
+
+@Suite
+struct MRecommendationPersonalTests {
+  @Test
+  func personalRecommendationsRequestSetsLimit() {
+    let request = MRecommendation.personalRecommendationsRequest(limit: 12)
+    #expect(request.limit == 12)
+  }
+
+  @Test
+  func personalRecommendationsRequestAllowsNilLimit() {
+    let request = MRecommendation.personalRecommendationsRequest(limit: nil)
+    #expect(request.limit == nil)
+  }
+}

Tests/MusadoraKitTests/Summaries/MSummaryFacadeTests.swift

@@ -0,0 +1,54 @@
+import Foundation
+@testable import MusadoraKit
+import Testing
+
+@Suite
+struct MSummaryFacadeTests {
+  @Test
+  func latestRequestUsesDefaults() throws {
+    let request = MSummary.requestForLatest(
+      views: [.topAlbums, .topArtists, .topSongs],
+      languageTag: nil,
+      include: nil,
+      extend: nil
+    )
+
+    #expect(request.period == .latestYear)
+    #expect(request.views == [.topAlbums, .topArtists, .topSongs])
+    #expect(request.languageTag == nil)
+    #expect(request.include == nil)
+    #expect(request.extend == nil)
+  }
+
+  @Test
+  func latestMonthRequestBuildsExpectedPeriod() throws {
+    let calendar = Calendar(identifier: .gregorian)
+    let timeZone = TimeZone(secondsFromGMT: 0) ?? .current
+    var components = DateComponents()
+    components.calendar = calendar
+    components.timeZone = timeZone
+    components.year = 2025
+    components.month = 2
+    components.day = 15
+    let now = try #require(components.date)
+
+    let context = MSummary.LatestMonthContext(
+      calendar: calendar,
+      now: now,
+      timeZone: timeZone
+    )
+    let request = try MSummary.requestForLatestMonth(
+      views: [.topSongs],
+      languageTag: "en-US",
+      include: ["relationships"],
+      extend: ["extended-attributes"],
+      context: context
+    )
+
+    #expect(request.period == .month(year: 2025, month: 1))
+    #expect(request.views == [.topSongs])
+    #expect(request.languageTag == "en-US")
+    #expect(request.include == ["relationships"])
+    #expect(request.extend == ["extended-attributes"])
+  }
+}