chore: Adding missing Given/Then/When comments to all new tests

AmplifyPlugins/Auth/Tests/AWSCognitoAuthPluginUnitTests/ActionTests/CredentialStore/MigrateLegacyCredentialStoreTests.swift

@@ -126,7 +126,10 @@ class MigrateLegacyCredentialStoreTests: XCTestCase {
         )
     }
 
-    func testInvalidEnvironment() async {
+    /// - Given: A credential store with an invalid environment
+    /// - When: The migration legacy store action is executed
+    /// - Then: An error event of type configuration is dispatched
+    func testExecute_withInvalidEnvironment_shouldDispatchError() async {
         let expectation = expectation(description: "noEnvironment")
         let action = MigrateLegacyCredentialStore()
         await action.execute(
@@ -145,7 +148,12 @@ class MigrateLegacyCredentialStoreTests: XCTestCase {
         await fulfillment(of: [expectation], timeout: 1)
     }
 
-    func testNoUserPoolWithoutLoginsTokens() async {
+    /// - Given: A credential store with an environment that only has identity pool
+    /// - When: The migration legacy store action is executed
+    /// - Then: 
+    ///     - A .loadCredentialStore event with type .amplifyCredentials is dispatched
+    ///     - An .identityPoolOnly credential is saved
+    func testExecute_withoutUserPool_andWithoutLoginsTokens_shouldDispatchLoadEvent() async {
         let expectation = expectation(description: "noUserPoolTokens")
         let action = MigrateLegacyCredentialStore()
         await action.execute(
@@ -183,7 +191,11 @@ class MigrateLegacyCredentialStoreTests: XCTestCase {
         await fulfillment(of: [expectation], timeout: 1)
     }
 
-    func testNoUserPoolWithLoginsTokens() async {
+    /// - Given: A credential store with an environment that only has identity pool
+    /// - When: The migration legacy store action is executed
+    ///     - A .loadCredentialStore event with type .amplifyCredentials is dispatched
+    ///     - An .identityPoolWithFederation credential is saved
+    func testExecute_withoutUserPool_andWithLoginsTokens_shouldDispatchLoadEvent() async {
         let expectation = expectation(description: "noUserPoolTokens")
         let action = MigrateLegacyCredentialStore()
         await action.execute(

AmplifyPlugins/Auth/Tests/AWSCognitoAuthPluginUnitTests/ActionTests/FetchAuthSession/FetchUserPoolTokens/RefreshHostedUITokensTests.swift

@@ -20,6 +20,23 @@ class RefreshHostedUITokensTests: XCTestCase {
         "expires_in": 10
     ]
 
+    private var hostedUIEnvironment: HostedUIEnvironment {
+        BasicHostedUIEnvironment(
+            configuration: .init(
+                clientId: "clientId",
+                oauth: .init(
+                    domain: "cognitodomain",
+                    scopes: ["name"],
+                    signInRedirectURI: "myapp://",
+                    signOutRedirectURI: "myapp://"
+                )
+            ),
+            hostedUISessionFactory: sessionFactory,
+            urlSessionFactory: urlSessionMock,
+            randomStringFactory: mockRandomString
+        )
+    }
+
     override func setUp() {
         let result = try! JSONSerialization.data(withJSONObject: tokenResult)
         MockURLProtocol.requestHandler = { _ in
@@ -31,7 +48,10 @@ class RefreshHostedUITokensTests: XCTestCase {
         MockURLProtocol.requestHandler = nil
     }
 
-    func testValidSuccessfulResponse() async {
+    /// Given: A RefreshHostedUITokens action
+    /// When: execute is invoked with a valid response
+    /// Then: A RefreshSessionEvent.refreshIdentityInfo is dispatched
+    func testExecute_withValidResponse_shouldDispatchRefreshEvent() async {
         let expectation = expectation(description: "refreshHostedUITokens")
         let action = RefreshHostedUITokens(existingSignedIndata: .testData)
         action.execute(
@@ -57,7 +77,10 @@ class RefreshHostedUITokensTests: XCTestCase {
         await fulfillment(of: [expectation], timeout: 1)
     }
 
-    func testServiceError() async {
+    /// Given: A RefreshHostedUITokens action
+    /// When: execute is invoked and throws a HostedUIError
+    /// Then: A RefreshSessionEvent.throwError is dispatched with .service
+    func testExecute_withHostedUIError_shouldDispatchErrorEvent() async {
         let expectedError = HostedUIError.serviceMessage("Something went wrong")
         MockURLProtocol.requestHandler = { _ in
             throw expectedError
@@ -86,7 +109,10 @@ class RefreshHostedUITokensTests: XCTestCase {
         await fulfillment(of: [expectation], timeout: 1)
     }
 
-    func testEmptyData() async {
+    /// Given: A RefreshHostedUITokens action
+    /// When: execute is invoked and returns empty data
+    /// Then: A RefreshSessionEvent.throwError is dispatched with .service
+    func testExecute_withEmptyData_shouldDispatchErrorEvent() async {
         MockURLProtocol.requestHandler = { _ in
             return (HTTPURLResponse(), Data())
         }
@@ -121,7 +147,10 @@ class RefreshHostedUITokensTests: XCTestCase {
         await fulfillment(of: [expectation], timeout: 1)
     }
 
-    func testInvalidTokens() async {
+    /// Given: A RefreshHostedUITokens action
+    /// When: execute is invoked and returns data that is invalid for tokens
+    /// Then: A RefreshSessionEvent.throwError is dispatched with .invalidTokens
+    func testExecute_withInvalidTokens_shouldDispatchErrorEvent() async {
         let result: [String: Any] = [
             "key": "value"
         ]
@@ -153,7 +182,10 @@ class RefreshHostedUITokensTests: XCTestCase {
         await fulfillment(of: [expectation], timeout: 1)
     }
 
-    func testErrorResponse() async {
+    /// Given: A RefreshHostedUITokens action
+    /// When: execute is invoked and returns data representing an error
+    /// Then: A RefreshSessionEvent.throwError is dispatched with .service
+    func testExecute_withErrorResponse_shouldDispatchErrorEvent() async {
         let result: [String: Any] = [
             "error": "Error.",
             "error_description": "Something went wrong"
@@ -193,7 +225,10 @@ class RefreshHostedUITokensTests: XCTestCase {
         await fulfillment(of: [expectation], timeout: 1)
     }
 
-    func testNoHostedUIEnvironment() async {
+    /// Given: A RefreshHostedUITokens action
+    /// When: execute is invoked without a HostedUIEnvironment
+    /// Then: A RefreshSessionEvent.throwError is dispatched with .noUserPool
+    func testExecute_withoutHostedUIEnvironment_shouldDispatchErrorEvent() async {
         let expectation = expectation(description: "noHostedUIEnvironment")
         let action = RefreshHostedUITokens(existingSignedIndata: .testData)
         action.execute(
@@ -217,7 +252,10 @@ class RefreshHostedUITokensTests: XCTestCase {
         await fulfillment(of: [expectation], timeout: 1)
     }
 
-    func testNoUserPoolEnvironment() async {
+    /// Given: A RefreshHostedUITokens action
+    /// When: execute is invoked without a UserPoolEnvironment
+    /// Then: A RefreshSessionEvent.throwError is dispatched with .noUserPool
+    func testExecute_withoutUserPoolEnvironment_shouldDispatchErrorEvent() async {
         let expectation = expectation(description: "noUserPoolEnvironment")
         let action = RefreshHostedUITokens(existingSignedIndata: .testData)
         action.execute(
@@ -237,24 +275,7 @@ class RefreshHostedUITokensTests: XCTestCase {
 
         await fulfillment(of: [expectation], timeout: 1)
     }
-
-    private var hostedUIEnvironment: HostedUIEnvironment {
-        BasicHostedUIEnvironment(
-            configuration: .init(
-                clientId: "clientId",
-                oauth: .init(
-                    domain: "cognitodomain",
-                    scopes: ["name"],
-                    signInRedirectURI: "myapp://",
-                    signOutRedirectURI: "myapp://"
-                )
-            ),
-            hostedUISessionFactory: sessionFactory,
-            urlSessionFactory: urlSessionMock,
-            randomStringFactory: mockRandomString
-        )
-    }
-
+
     private func identityProviderFactory() throws -> CognitoUserPoolBehavior {
         return MockIdentityProvider(
             mockInitiateAuthResponse: { _ in

AmplifyPlugins/Auth/Tests/AWSCognitoAuthPluginUnitTests/ActionTests/InitiateAuthSRP/VerifyDevicePasswordSRPSignatureTests.swift

@@ -23,6 +23,9 @@ class VerifyDevicePasswordSRPSignatureTests: XCTestCase {
         srpClient = nil
     }
 
+    /// Given: A VerifyDevicePasswordSRP
+    /// When: signature is invoked
+    /// Then: a non-empty string is returned
     func testSignature_withValidValues_shouldReturnSignature() async {
         do {
             let signature = try signature()
@@ -32,6 +35,9 @@ class VerifyDevicePasswordSRPSignatureTests: XCTestCase {
         }
     }
 
+    /// Given: A VerifyDevicePasswordSRP
+    /// When: signature is invoked and the srpClient throws an SRPError error when generating a shared secret
+    /// Then: a .calculation error is thrown
     func testSignature_withSRPErrorOnSharedSecret_shouldThrowCalculationError() async {
         srpClient.sharedSecret = .failure(SRPError.numberConversion)
         do {
@@ -47,6 +53,9 @@ class VerifyDevicePasswordSRPSignatureTests: XCTestCase {
         }
     }
 
+    /// Given: A VerifyDevicePasswordSRP
+    /// When: signature is invoked and the srpClient throws a non-SRPError error when generating a shared secret
+    /// Then: a .configuration error is thrown
     func testSignature_withOtherErrorOnSharedSecret_shouldThrowCalculationError() async {
         srpClient.sharedSecret = .failure(CancellationError())
         do {
@@ -62,6 +71,9 @@ class VerifyDevicePasswordSRPSignatureTests: XCTestCase {
         }
     }
 
+    /// Given: A VerifyDevicePasswordSRP
+    /// When: signature is invoked and the srpClient throws a SRPError error when generating an authentication key
+    /// Then: a .calculation error is thrown
     func testSignature_withSRPErrorOnAuthenticationKey_shouldThrowCalculationError() async {
         MockSRPClientBehavior.authenticationKey = .failure(SRPError.numberConversion)
         do {
@@ -77,6 +89,9 @@ class VerifyDevicePasswordSRPSignatureTests: XCTestCase {
         }
     }
 
+    /// Given: A VerifyDevicePasswordSRP
+    /// When: signature is invoked and the srpClient throws a non-SRPError error when generating an authentication key
+    /// Then: a .configuration error is thrown
     func testSignature_withOtherErrorOnAuthenticationKey_shouldThrowCalculationError() async {
         MockSRPClientBehavior.authenticationKey = .failure(CancellationError())
         do {

AmplifyPlugins/Auth/Tests/AWSCognitoAuthPluginUnitTests/ActionTests/SignOut/ShowHostedUISignOutTests.swift

@@ -24,6 +24,9 @@ class ShowHostedUISignOutTests: XCTestCase {
         mockHostedUIResult = nil
     }
 
+    /// Given: A ShowHostedUISignOut action with global sign out set to true
+    /// When: execute is invoked with a success result
+    /// Then: A .signOutGlobally event is dispatched with a nil error
     func testExecute_withGlobalSignOut_andSuccessResult_shouldDispatchSignOutEvent() async {
         let expectation = expectation(description: "showHostedUISignOut")
         let signInData = SignedInData.testData
@@ -56,6 +59,9 @@ class ShowHostedUISignOutTests: XCTestCase {
         await fulfillment(of: [expectation], timeout: 1)
     }
 
+    /// Given: A ShowHostedUISignOut action with global sign out set to false
+    /// When: execute is invoked with a success result
+    /// Then: A .revokeToken event is dispatched
     func testExecute_withLocalSignOut_andSuccessResult_shouldDispatchSignOutEvent() async {
         let expectation = expectation(description: "showHostedUISignOut")
         let signInData = SignedInData.testData
@@ -87,6 +93,9 @@ class ShowHostedUISignOutTests: XCTestCase {
         await fulfillment(of: [expectation], timeout: 1)
     }
 
+    /// Given: A ShowHostedUISignOut action
+    /// When: execute is invoked but fails to create a HostedUI session
+    /// Then: A .userCancelled event is dispatched
     func testExecute_withInvalidResult_shouldDispatchUserCancelledEvent() async {
         mockHostedUIResult = .failure(.cancelled)
         let signInData = SignedInData.testData
@@ -117,6 +126,9 @@ class ShowHostedUISignOutTests: XCTestCase {
         await fulfillment(of: [expectation], timeout: 1)
     }
 
+    /// Given: A ShowHostedUISignOut action
+    /// When: execute is invoked but fails to create a HostedUI session with a HostedUIError.signOutURI
+    /// Then: A .signOutGlobally event is dispatched with a HosterUIError.configuration error
     func testExecute_withSignOutURIError_shouldThrowConfigurationError() async {
         mockHostedUIResult = .failure(HostedUIError.signOutURI)
         let signInData = SignedInData.testData
@@ -157,6 +169,9 @@ class ShowHostedUISignOutTests: XCTestCase {
         await fulfillment(of: [expectation], timeout: 1)
     }
 
+    /// Given: A ShowHostedUISignOut action
+    /// When: execute is invoked but fails to create a HostedUI session with a HostedUIError.invalidContext
+    /// Then: A .signOutGlobally event is dispatched with a HosterUIError.invalidState error
     func testExecute_withInvalidContext_shouldThrowInvalidStateError() async {
         mockHostedUIResult = .failure(HostedUIError.invalidContext)
         let signInData = SignedInData.testData
@@ -198,6 +213,9 @@ class ShowHostedUISignOutTests: XCTestCase {
         await fulfillment(of: [expectation], timeout: 1)
     }
 
+    /// Given: A ShowHostedUISignOut action with an invalid SignOutRedirectURI
+    /// When: execute is invoked
+    /// Then: A .signOutGlobally event is dispatched with a HosterUIError.configuration error
     func testExecute_withInvalidSignOutURI_shouldThrowConfigurationError() async {
         signOutRedirectURI = "invalidURI"
         let signInData = SignedInData.testData
@@ -238,6 +256,9 @@ class ShowHostedUISignOutTests: XCTestCase {
         await fulfillment(of: [expectation], timeout: 1)
     }
 
+    /// Given: A ShowHostedUISignOut action
+    /// When: execute is invoked with a nil HostedUIEnvironment
+    /// Then: A .signOutGlobally event is dispatched with a HosterUIError.configuration error
     func testExecute_withoutHostedUIEnvironment_shouldThrowConfigurationError() async {
         let expectation = expectation(description: "noHostedUIEnvironment")
         let signInData = SignedInData.testData
@@ -275,6 +296,9 @@ class ShowHostedUISignOutTests: XCTestCase {
         await fulfillment(of: [expectation], timeout: 1)
     }
 
+    /// Given: A ShowHostedUISignOut action
+    /// When: execute is invoked with an invalid environment
+    /// Then: A .signOutGlobally event is dispatched with a HosterUIError.configuration error
     func testExecute_withInvalidUserPoolEnvironment_shouldThrowConfigurationError() async {
         let expectation = expectation(description: "invalidUserPoolEnvironment")
         let signInData = SignedInData.testData

AmplifyPlugins/Auth/Tests/AWSCognitoAuthPluginUnitTests/CognitoASFTests/CognitoUserPoolASFTests.swift

@@ -18,7 +18,10 @@ class CognitoUserPoolASFTests: XCTestCase {
     override func tearDown() {
         pool = nil
     }
-
+
+    /// Given: A CognitoUserPoolASF
+    /// When: userContextData is invoked
+    /// Then: A non-empty string is returned
     func testUserContextData_shouldReturnData() throws {
         let result = try pool.userContextData(
             for: "TestUser",
@@ -29,11 +32,24 @@ class CognitoUserPoolASFTests: XCTestCase {
         XCTAssertFalse(result.isEmpty)
     }
 
-    func testcalculateSecretHash_withInvalidClientId_shouldThrowHashKeyError() {
+    /// Given: A CognitoUserPoolASF
+    /// When: calculateSecretHash is invoked
+    /// Then: A non-empty string is returned
+    func testCalculateSecretHash_shouldReturnHash() throws {
+        let result = try pool.calculateSecretHash(
+            contextJson: "contextJson",
+            clientId: "clientId"
+        )
+    }
+
+    /// Given: A CognitoUserPoolASF
+    /// When: calculateSecretHash is invoked with a clientId that cannot be parsed
+    /// Then: A ASFError.hashKey is thrown
+    func testCalculateSecretHash_withInvalidClientId_shouldThrowHashKeyError() {
         do {
             let result = try pool.calculateSecretHash(
                 contextJson: "contextJson",
-                clientId: "🕺🏼"
+                clientId: "🕺🏼" // This string cannot be represented using .ascii, so it will throw an error
             )
             XCTFail("Expected ASFError.hashKey, got \(result)")
         } catch let error as ASFError {

AmplifyPlugins/Auth/Tests/AWSCognitoAuthPluginUnitTests/Support/AWSAuthCognitoSessionTests.swift

@@ -63,6 +63,9 @@ class AWSAuthCognitoSessionTests: XCTestCase {
         XCTAssertFalse(cognitoTokens.doesExpire())
     }
 
+    /// Given: An AWSAuthCognitoSession with a valid AWSCognitoUserPoolTokens
+    /// When: getUserSub is invoked
+    /// Then: The "sub" from the token data should be returned
     func testGetUserSub_shouldReturnResult() {
         let tokenData = [
             "sub": "1234567890",
@@ -92,6 +95,9 @@ class AWSAuthCognitoSessionTests: XCTestCase {
         XCTAssertEqual(userSub, "1234567890")
     }
 
+    /// Given: An AWSAuthCognitoSession with a AWSCognitoUserPoolTokens that does not include a "sub" attribute
+    /// When: getUserSub is invoked
+    /// Then: A .failure with AuthError.unknown error is returned
     func testGetUserSub_withoutSub_shouldReturnError() {
         let tokenData = [
             "name": "John Doe",
@@ -122,6 +128,9 @@ class AWSAuthCognitoSessionTests: XCTestCase {
         XCTAssertEqual(errorDescription, "Could not retreive user sub from the fetched Cognito tokens.")
     }
 
+    /// Given: An AWSAuthCognitoSession that is signed out
+    /// When: getUserSub is invoked
+    /// Then: A .failure with AuthError.signedOut error is returned
     func testGetUserSub_signedOut_shouldReturnError() {
         let error = AuthError.signedOut("", "", nil)
         let session = AWSAuthCognitoSession(
@@ -141,6 +150,9 @@ class AWSAuthCognitoSessionTests: XCTestCase {
         XCTAssertEqual(recoverySuggestion, AuthPluginErrorConstants.userSubSignOutError.recoverySuggestion)
     }
 
+    /// Given: An AWSAuthCognitoSession that has a service error
+    /// When: getUserSub is invoked
+    /// Then: A .failure with AuthError.signedOut error is returned
     func testGetUserSub_serviceError_shouldReturnError() {
         let serviceError = AuthError.service("Something went wrong", "Try again", nil)
         let session = AWSAuthCognitoSession(
@@ -158,6 +170,9 @@ class AWSAuthCognitoSessionTests: XCTestCase {
         XCTAssertEqual(error, serviceError)
     }
 
+    /// Given: An AuthAWSCognitoCredentials and an AWSCognitoUserPoolTokens instance
+    /// When: Two AWSAuthCognitoSession are created from the same values
+    /// Then: The two AWSAuthCognitoSession are considered equal
     func testSessionsAreEqual() {
         let expiration = Date(timeIntervalSinceNow: 121)
         let tokenData = [