WireMock with HTTPS for Android Tests

Getting the details right can be tricky

When it comes to mocking HTTP communication in Android tests, there are two popular libraries for doing so — WireMock and MockWebServer (part of OkHttp). They’re both capable frameworks with similar functionality and both support HTTPS. I suggest you check out both to see which is a better fit for your use cases. This post, however, is about setting up WireMock with basic HTTPS support. It took me quite a while to work through the details, which are largely undocumented.

Of course, when setting up HTTPS, the first thing you will need is a certificate. WireMock does bundle a self-signed default certificate, but the Keystore itself is in JKS format, which Android does not support. What I am about to describe to create your own certificate can be done using command line tools. However, it is much easier using a tool like KeyStore Explorer, which I will show you how to do in this post.

• Once you have downloaded and launched KeyStore Explorer, you will be shown a start screen where you can choose to Create a New KeyStore.
• For the KeyStore type, choose BKS (Bouncy Castle).
• From the Tools menu, choose Generate Key Pair.
• On the resulting dialog, the default options should be fine — RSA with a 2,048-bit key.
• On the resulting dialog, you will likely want to change the Validity Period to something like 99 years.
• Click the button next to the Name field to edit the name. What you enter into these fields isn’t super important, but see the following example as inspiration:

• And lastly, you will need to add an extension.
• Click the green plus (+) to the right of the list on the extensions dialog.
• Choose Subject Alternative Name as the type, from the bottom of the list.
• Click the green plus (+) on the resulting dialog.
• Choose IP Address as the type.
• Enter 127.0.0.1 as the value (this will need to match your WireMock bind address in your tests).
• Now you can click OK on each of the dialogs. You will be prompted for an alias for the Keystore entry, as well as a password. Enter whatever values make sense to you (but do enter a password).
• Now you can save your Keystore. It’s very important that you leave the password fields blank. WireMock does not support a password on the Keystore itself. You should save the Keystore into the assets directory under your androidTest source set.

Now, you have a self-signed certificate within a Keystore type that Android supports. It’s time to actually setup WireMock in your project. This page talk about the basics of setting up WireMock in an Android project, and this page talks about the basics of setting up HTTPS with WireMock. I am going to fill in the blanks for setting up HTTPS on Android.

Let’s start with the changes necessary within your build script (build.gradle). The first thing you need to know is, based on your minimum SDK version, you may need to enable multidex support (this is for versions 19 and below). Hopefully your minimum SDK isn’t that low, but I’ll include instructions for that just in case. Here are the androidTestImplementation dependencies that I have added:

Also, within your android.defaultConfig block, make sure you have multiDexEnabled true. You will need to make changes to your AndroidManifest.xml file (if you don’t have this file under your androidTest source root, add one):

Now your project is setup for WireMock, so let’s actually use it within some tests. The first thing you need to do is add the WireMock rule to your test class:

@Rule @JvmField val wireMockRule: WireMockRule

You need to create a constructor so that you can copy the truststore file to an accessible location on disk and initialize your WireMock rule.

If the bind address does not match the SAN on the certificate you created, then you will need to create a HostnameVerifier to reconcile this difference. It’s easiest to just have them match. The response stubbing and making the HTTP request itself are outside of the scope of this post, but you will specify the URL like so:

"https://127.0.0.1:${wireMockRule.httpsPort()}"

Since you are using a self-signed certificate, the chain of trust cannot be validated. For this reason, you will need to specify an X509TrustManager for your tests. This will allow your insecure certificate to be used. How this is done will depend on which framework you’re using for HTTP communication, but here’s an example using the platform classes:

Summary

In this post, I have walked you through how to generate a self-signed SSL certificate for use with WireMock in your Android tests. I have shown you how to add WireMock to your project, as well as use it in your test class. This is similar in concept to the steps to Configure MockWebServer, but the classes used to configure the HTTP mocking to use the certificate are somewhat different. I hope you have found this useful!