Forem: Manuel Enrique Mariñez

Appium: Capture Inbox Link for Email Based Login

Manuel Enrique Mariñez — Thu, 08 Feb 2024 11:51:10 +0000

On this post I'll show you how to implement a solution to bypass an email based login in which a verification email is sent to your inbox and the deep link opens the app for you to continue the automated test.

I'll be using the following tools and services for the code snippets but a similar approach can be applied to other tech stack:

Appium
Kotlin
Retrofit2
Mailsac

First, we will have to go to mailsac and create an account. Don't worry about pricing, for this example, the free tier provides us with 1500 opts per months (the opts are equivalent to API calls, email inbox, etc), it is more than enough for a small to mid test automation project (assuming it has low rate of automated weekly iterations).

Once we complete sign up and we are logged in our account, go fill the input mail at the top left side of the page and click Check the mail! button.

Once we validated the access the created inbox, go back to our dashboard and look for our API Key (that we will need to access the inbox via REST API). See the following steps:

In the dashboard locate the API Keys section and click on "create API secret".

Then you will click on Manage Keys.

From there add a name for your API Key (it can be anything you can identify) and save the API KEY since it won't show up again and we will need it later on.

The Setup

With our mailsac account created and our API Key saved, let's start the implementation.

At First is worth testing the API call to see that everything is working as expected. Open your terminal and add the following command (replace api-key and your-mail-inbox with your info):

curl -H 'Mailsac-Key: <api_key>' https://mailsac.com/api/addresses/<your-mail-inbox>/messages

The response should be empty list "[]" since we haven't received, any emails yet, but you can test on your own by sending a mail to the mailbox. Here's an example of what the response looks like with at least one mail in the inbox (it won't be formatted when you see it but for the sake of this blog post I'll make it look pretty):


{

   "_id":"59w9HezR_PinWSOHl09yeoa",

   "from":[

      {

         "address":"test.test@test.com",

         "name":"Test User"

      }

   ],

   "to":[

      {

         "address":"test@mailsac.com",

         "name":"Tester"

      }

   ],

   "cc":[



   ],

   "bcc":[



   ],

   "subject":"test mail",

   "savedBy":null,

   "inbox":"test@mailsac.com",

   "originalInbox":"test@mailsac.com",

   "domain":"mailsac.com",

   "received":"2023-02-05T22:27:06.266Z",

   "size":3070,

   "attachments":[



   ],

   "ip":"",

   "via":"",

   "folder":"inbox",

   "labels":[



   ],

   "read":null,

   "rtls":true,

   "links":[

      "https://www.google.com/"

   ],

   "spam":0

}

As you can see, we get a LOT of information from our mail, and from it, we see a "key" called "links", that is what we are targeting to get from our API request.

Now let's jump to the code to implement our solution:

We will need to setup our HTTP interpreter with Retrofit2. For that we will need the classes below (I'll explain the code from top to bottom):

class ServiceGenerator {

    private val baseURL = "https://mailsac.com/api/addresses/"
    private val AuthKey = System.getenv("MAILSAC_ACCESS_KEY")
    private val Interceptor = EmailAuthenticationInterceptor(AuthKey)
    private val emailHttpClient = OkHttpClient.Builder().addInterceptor(Interceptor)

    private val builderEmail: Retrofit.Builder = Retrofit.Builder()
           .baseUrl(URL)
           .addConverterFactory(GsonConverterFactory.create())

    private var retrofit: Retrofit = builder.build()

    fun <S> createServiceEmail(serviceClass: Class<S>): S {
        retrofit = builderEmail.client(emailHttpClient.build()).build()
        return retrofit.create(serviceClass)
    }
}

Create serviceGenerator class that will contain our key and request interceptor usage.
Initialize AuthKey variable that will contain our mailsac API key. (Here I'm calling an environment variable for security reasons but you can save it on a file, a string or Json file. Whatever works for you).
Initialize our interceptor variable that contains the Object of a class we will see later on. Pass the AuthKey as argument.
Initialize your http interpreter.
Setup your Retrofit builder (I explained it in a previous blog, the retrofit will manage your request in a lower level)
Create your service method (This is what we will handle and interpret the requests)

import java.io.IOException
import okhttp3.Interceptor
import okhttp3.Response


class EmailAuthenticationInterceptor(private val authToken: String) : Interceptor {
    @Throws(IOException::class)
    override fun intercept(chain: Interceptor.Chain): Response {
        val original = chain.request()
        val builderWithAuth = original.newBuilder()
            .header("Mailsac-Key", authToken)
            .build()
        return chain.proceed(builderWithAuth)
    }
}

Create the EmailAuthenticationInterceptor class that receives a string as a parameter (this is expecting the API key).
Create override method intercept from which we manage the headers we will be passing in our request, in this case the API key with the key "Mailsac-Key".

import okhttp3.MultipartBody
import retrofit2.Call
import okhttp3.RequestBody
import okhttp3.ResponseBody
import retrofit2.http.*
import java.io.File

interface MessageService {

    @GET("<user-email>/messages")
    fun getEmails(): Call<ResponseBody>
}

Setup interface that handles the REST API methods.
GET method annotation then receives the endpoint part with the your email inbox created in mailsac.
Setup method type Call ResponseBody .

Finally we have everything we need to use our solution.

This final stage will always depend on the usage that you need, but for our case scenario we will catch the link we need to verify the login.

At this point, I'll assumed you've already setup your steps to have the mail sent to your inbox , so in order to catch the info we need here is one approach you can use:

val service = ServiceGenerator().createServiceEmail(MessageService::class.java)
val response: Response<ResponseBody> = service.getEmails().execute()
val responseBody: String = response.body()!!.string()

val responseJsonArray = JsonParser.parseString(responseBody).asJsonArray

for(jsonElement in responseJsonArray){
           val jsonObject = jsonElement.asJsonObject
           val appUrl = jsonObject.get("links").asString
                openLink(driver, appUrl)
                break

        }

As you can see, initializing the service is straight forward:

We call our service by passing the MessageService
Get the response by calling our "getMails()" method and executing the request.
Parse the Json as a Jsonarray
Finally iterate trough it until you get the link you need.
The openLink() method is just a wrapped "drive.get()" method.

This is the end of the walkthrough. I wanted to share this solution with anyone looking for a way to automate a similar process. There are many other ways to do it, but this one in particular is suited for a local and test environments using CI tools if you like, since you won't need a user interaction of any kind, everything is handle via API, you won't need to update a token or have the need to add extra steps for an exception, (Gmail API for example has this problem).

Hopefully you find this solution walktrough useful and if you have any feedback or know any libraries that can facilitate a similar progress, please share it in the comments below.

Retrofit2: An Appium Implementation to Upload APKs to Browserstack

Manuel Enrique Mariñez — Fri, 20 Oct 2023 11:16:27 +0000

All right the following implementation will be done based on a Gradle project using Kotlin but others build automation tools may follow a similar approach. With that taken out of the way let's start with the dependencies you are going to need in order to use retrofit2.

Dependencies:

implementation("com.squareup.retrofit2:retrofit:2.9.0")
implementation("com.squareup.retrofit2:converter-gson:2.9.0")
implementation("com.squareup.okhttp3:okhttp:4.11.0")
implementation("com.squareup.okhttp3:logging-interceptor:4.11.0")

Once that is all set "sync" your gradle file for this changes to be applied.

Now that retrofit2 is up and running in our project let's go to our "Driver" class to setup our service generator that is going to help us interact with the requests needed to upload our APK to the Browserstack platform.

First lets import our libraries and start our service:

import okhttp3.MediaType.Companion.toMediaTypeOrNull
import okhttp3.MultipartBody
import okhttp3.RequestBody.Companion.asRequestBody
import okhttp3.ResponseBody
import retrofit2.Response

private val service = ServiceGenerator().createService(FileUploadService::class.java)

By now you might be wondering "why are we using okhttp3? isn't this about retrofit2? What is this ServiceGenerator() class? Did I miss a page?"

These are questions I too struggled a lot to understand at first, so we will go step by step.

OkHttp3 is used for making HTTP requests and managing network connections. It simplifies the process of sending requests, handling responses, and managing the underlying network infrastructure. Retrofit2 is also a network handler capable of building and executing HTTP request. Both of these technologies are develop by the same company Square INC and they complement each other, while OkHttp focuses on managing low-level HTTP connections, Retrofit is a higher-level library that simplifies the process of interacting with RESTful web services.

The ServiceGenerator() class is a utility class used in Retrofit implementations to create and configure instances of Retrofit service interfaces. This class typically encapsulates the setup of the Retrofit client and the creation of service instances.

Now we will go ahead and create our kotlin class for the Service Generator. It should look like the following:

import okhttp3.Credentials
import okhttp3.OkHttpClient
import retrofit2.Retrofit
import retrofit2.converter.gson.GsonConverterFactory
import utils.AuthenticationInterceptor

class ServiceGenerator {
    private val baseURL = "https://api-cloud.browserstack.com/"
    private val userName: String = System.getenv("BROWSERSTACK_USERNAME")
    private val accessKey: String = System.getenv("BROWSERSTACK_ACCESS_KEY")
    private val authToken = Credentials.basic(userName, accessKey)
    private val interceptor = AuthenticationInterceptor(authToken)
    private val httpClient = OkHttpClient.Builder().addInterceptor(interceptor)

    private val builder: Retrofit.Builder = Retrofit.Builder()
        .baseUrl(baseURL)
        .addConverterFactory(GsonConverterFactory.create())

    private var retrofit: Retrofit = builder.build()

    fun <S> createService(serviceClass: Class<S>): S {
        retrofit = builder.client(httpClient.build()).build()
        return retrofit.create(serviceClass)
    }
}

What are we setting up here?

Base URL for the Browserstack URL
Browserstack credentials (recommended to be stored in environment variables)
Basic Credentials handler by the Okhttp3 library
Authorization interceptor (also known to be our header handler we will see more of it next for the implementation)
Finally the rest of the code shows how to setup the httpClient to handle all the data we are going to send trough the service in order to execute the requests we need for the apk upload where lastly there is the createService method that will return the retrofit service we need.

Now as previously mention in step 4, we are going to need a hearder handler and for that we are going to create yet another kotlin class that contains the following:

import java.io.IOException
import okhttp3.Interceptor
import okhttp3.Response


class AuthenticationInterceptor(private val authToken: String) : Interceptor {
    @Throws(IOException::class)
    override fun intercept(chain: Interceptor.Chain): Response {
        val original = chain.request()
        val builderWithAuth = original.newBuilder()
            .header("Authorization", authToken)
            .header("Content-Type", "multipart/form-data")
            .build()
        return chain.proceed(builderWithAuth)
    }
}

In my particular case I end up calling this class AuthenticationInterceptor because it's main function for me was to handle my browser credentials but something like HeaderInterceptor would be more appropriate since it able to manage any required header parameter. But by now authorization and content type is all we need. Authorization for our Browserstack credentials and Content-type to let know the server what content we will be uploading in our request.

Well we are almost done with the setup and there is one last thing we need to take into consideration, at the beginning the service call you might have notice that we are passing FileUploadService as an argument for our service, that is our next step, the interface that will manage our RESTAPI methods (Get, Post, etc...).

This time we are going to create an Interface file that manages Get and Post requests (we will mainly need Post for the upload but later on we will need Get for upload validation).

import okhttp3.MultipartBody
import retrofit2.Call
import okhttp3.ResponseBody
import retrofit2.http.*

interface FileUploadService {
    @Multipart
    @POST("app-automate/upload")
    fun upload(
        @Part fileMultiPart: MultipartBody.Part
    ): Call<Void>

    @GET("app-automate/recent_apps") 
    fun getRecentApps(): Call<ResponseBody>
}

In here we can spot the following:

Multipart annotation to highlight that we are going to be handling a multipart file upload (this is why earlier we added the Content-type multipart in the header handler).
Post annotation with the endpoint app-automate/upload, with this we are going to manage our post request and the endpoint we are pointing to in the Browserstack API.
Our upload method that contains the file multipart parameter that we will be passing in the usage
The return type void since we won't need to return any values (This could also be manage with a RequestBody return type).
Finally Our Get manager called getRecentApps with a similar structure as our Post manager but without needed parameters

With this we finally finish with our service set up, now let's go back to our Driver class for the usage.

private val service = ServiceGenerator().createService(FileUploadService::class.java)

With our service up and running we will now create our upload method that will send the requests and indicate our desired APK to bu uploaded.

private fun uploadFileRetrofit() {

        // Get apk file
        val file = File("./src/test/resources/apps/Sample.apk")

        // MultipartBody.part is used to send also the actual file name
        val fileRequest = file.asRequestBody("application/vnd.android.package-archive".toMediaTypeOrNull())

        val apkPart = MultipartBody.Part.createFormData("file", file.name, fileRequest)

        // Execute the Request
        val call = service.upload(apkPart)
        val response = call.execute()

        if (response.isSuccessful) {
            println("APK upload successful")
        } else {
            println("APK upload failed")
            println(response.errorBody()?.string())
        }

    }

Now in here we see the following implementations:

We highlight our file location within the project with the File library (imported with import java.io.File)
Set up the file as a request body and add it's media type for APKs ("application/vnd.android.package-archive")
Multipart body creation with the file name parameter, file name of the actual file we are uploading and the file's request body.

I can't stress enough how important is to add the "file" argument in the file name parameter as this is the argument expected from the Browserstack API. I scratched my head A LOT the first time implementing retrofit2 and I was getting a mislead error message all because I wasn't sending this parameter correctly.

We then call our upload method from our service interface and pass our now converted apk multipart (apkPart).
Request call execution.
Finally the response validation

This is all you need in order to upload a file using retrofit now that the method is set. Below is a little example of how I use it that includes the "Get" request from our Interface previously created.

response = service.getRecentApps().execute()
            responseBody = response.body()!!.string()
            val isApkUploaded = responseBody.contains("\"app_name\":\"Sample.apk\"")

            if (isApkUploaded) {
                println("APK file 'Sample.apk' is already uploaded.")

                val responseJsonArray = JsonParser.parseString(responseBody).asJsonArray
                for(jsonElement in responseJsonArray){
                    val jsonObject = jsonElement.asJsonObject
                    val appId = jsonObject.get("app_id")
                    return appId.asString
                }

            } else {
                println("APK file 'Sample.apk' is not uploaded.")
                uploadFileRetrofit()

                response = service.getRecentApps().execute()
                responseBody = response.body()!!.string()

                val responseJsonArray = JsonParser.parseString(responseBody).asJsonArray
                for(jsonElement in responseJsonArray){
                    val jsonObject = jsonElement.asJsonObject
                    val appId = jsonObject.get("app_id")
                    return appId.asString
                }
            }

And even after all that you might be wondering "Why would I do all this if I can just setup a method that sends the cURL command that I need to upload a file given by the Browserstack documentation itself?", and you are not wrong that was literally my first approach and it WORKS, but I though on sharing this more abstract and programmatically "organized" way to handle file uploads in automation projects for anyone interested in trying new ways adding a more maintainable code. Thank you for your time if you reach this part and see you in the next one.