Revised comments and name for confirmation overload, added tests

Author: Michael Mroz

src/main/java/com/auth0/guardian/Guardian.java

@@ -86,9 +86,6 @@ public Transaction requestEnroll(String ticket, EnrollmentType type)
      * transaction initiated with {@link EnrollmentType#TOTP()}) or when the user received the OTP code delivered to his
      * phone number by SMS (for a transaction initiated with {@link EnrollmentType#SMS(String)}).
      *
-     * This method can be used in stateful applications where a {@link Transaction} is preserved in memory between user
-     * interactions.
-     *
      * @param transaction the enrollment transaction
      * @param otp         the code obtained from the TOTP app or delivered to the phone number by SMS
      * @return extra information about the enrollment, like the recovery code
@@ -119,16 +116,16 @@ public Enrollment confirmEnroll(Transaction transaction, String otp)
      * transaction initiated with {@link EnrollmentType#TOTP()}) or when the user received the OTP code delivered to his
      * phone number by SMS (for a transaction initiated with {@link EnrollmentType#SMS(String)}).
      *
-     * This method can be used in stateless applications where {@link Transaction} may not be preserved between user
-     * interactions.
+     * This overload is intended for stateless applications where {@link java.io.Serializable} is not acceptable,
+     * avoiding the necessity of utilising poor practises to preserve {@link Transaction} between user actions.
      *
      * @param transactionToken the token associated with the transaction to confirm.
      * @param otp              the code obtained from the TOTP app or delivered to the phone number by SMS
      * @throws IOException              when there's a connection issue
      * @throws IllegalArgumentException when the transaction is not valid
      * @throws GuardianException        when there's a Guardian specific issue (invalid otp for example)
      */
-    public void confirmEnrollStateless(String transactionToken, String otp)
+    public void confirmEnroll(String transactionToken, String otp)
             throws IOException, IllegalArgumentException, GuardianException {
         if (transactionToken == null) {
             throw new IllegalArgumentException("Invalid enrollment transaction");

src/test/java/com/auth0/guardian/GuardianTest.java

@@ -264,4 +264,57 @@ public void shouldFailConfirmationWhenOtpIsNull() throws Exception {
         guardian
                 .confirmEnroll(new Transaction("TRANSACTION_TOKEN", null, null), null);
     }
+
+    @Test
+    public void shouldConfirmEnrollOverload() throws Exception {
+        server.jsonResponse(MockServer.START_FLOW_VALID, 201);
+        server.emptyResponse();
+
+        Transaction transaction = guardian
+                .requestEnroll(ENROLLMENT_TICKET, EnrollmentType.TOTP());
+
+        guardian
+                .confirmEnroll(transaction.getTransactionToken(), OTP_CODE);
+
+        RecordedRequest startFlowRequest = server.takeRequest();
+
+        assertThat(startFlowRequest, hasMethodAndPath("POST", "/api/start-flow"));
+        assertThat(startFlowRequest, hasHeader("Content-Type", "application/json; charset=utf-8"));
+        assertThat(startFlowRequest, hasHeader("Authorization", "Ticket id=\"ENROLLMENT_TICKET\""));
+
+        Map<String, Object> startFlowBody = bodyFromRequest(startFlowRequest);
+        assertThat(startFlowBody, hasEntry("state_transport", (Object) "polling"));
+
+        RecordedRequest verifyOtpRequest = server.takeRequest();
+
+        assertThat(verifyOtpRequest, hasMethodAndPath("POST", "/api/verify-otp"));
+        assertThat(verifyOtpRequest, hasHeader("Content-Type", "application/json; charset=utf-8"));
+        assertThat(verifyOtpRequest, hasHeader("Authorization", "Bearer THE_TRANSACTION_TOKEN"));
+
+        Map<String, Object> verifyOtpBody = bodyFromRequest(verifyOtpRequest);
+        assertThat(verifyOtpBody, hasEntry("type", (Object) "manual_input"));
+        assertThat(verifyOtpBody, hasEntry("code", (Object) "OTP_CODE"));
+    }
+
+    @Test
+    public void shouldFailConfirmationOverloadWhenNoTokenIsProvided() throws Exception {
+        exception.expect(IllegalArgumentException.class);
+        exception.expectMessage("Invalid enrollment transaction");
+
+        server.emptyResponse();
+
+        guardian
+                .confirmEnroll((String)null, OTP_CODE);
+    }
+
+    @Test
+    public void shouldFailConfirmationOverloadWhenOtpIsNull() throws Exception {
+        exception.expect(IllegalArgumentException.class);
+        exception.expectMessage("Invalid OTP");
+
+        server.emptyResponse();
+
+        guardian
+                .confirmEnroll("TRANSACTION_TOKEN", null);
+    }
 }