How to Test File Upload on Android (Complete Guide)

File upload is a common touchpoint in Android apps—profile pictures, document sharing, media attachments, and backup flows all rely on moving a user‑selected file from the device to a server. When thi

Why File Upload Testing Matters on Android

File upload is a common touchpoint in Android apps—profile pictures, document sharing, media attachments, and backup flows all rely on moving a user‑selected file from the device to a server. When this path fails, the impact is immediate: users cannot complete a core task, they see cryptic error messages, or worse, the app crashes or leaks data.

In production, upload failures often stem from a combination of factors that unit tests miss:

• Permission gaps – runtime denial of READ_EXTERNAL_STORAGE or MANAGE_EXTERNAL_STORAGE on Android 13+.
• Intent resolution issues – the chosen file‑picker app returns a content:// URI that the upload code cannot read.
• Network interruptions – a switch from Wi‑Fi to cellular mid‑upload triggers a timeout that is not handled.
• File size limits – backend rejects files over a certain size, but the client shows a generic “upload failed” toast.
• Security oversights – uploading a file with a malicious filename can lead to path‑traversal on the server if the name is not sanitized.

Because these defects are triggered only when the app interacts with the real Android ecosystem (intents, storage providers, varying network stacks), a dedicated test strategy is essential. The following guide walks through a complete matrix, manual steps, automated scripts, and how autonomous, persona‑driven exploration can surface bugs that scripted tests never consider.

---

Building a Test Matrix for File Upload

A structured matrix helps you ensure coverage across functional, non‑functional, and security dimensions. Below is a comprehensive table that you can adapt to your app’s specific upload entry points (e.g., profile avatar, chat attachment, document upload).

You can expand or shrink this matrix based on risk. The key is to treat each row as a test case that can be executed manually, automated, or verified by an autonomous explorer.

---

Manual Testing Approach: Step‑by‑Step

Manual testing remains valuable for exploratory checks, UI polish, and validating error messages that are hard to assert in code. Below is a repeatable workflow you can follow on a physical device or an emulator.

1. Prepare the Test Environment

2. Execute the Happy Path

1. Launch the app and navigate to the upload screen (e.g., tap Profile → Change Photo).
2. Tap the Upload button. The system file picker should appear.
3. Choose Gallery → navigate to Download/sample.jpg → select it.
4. Observe:

• The picker closes and returns to the app.
• A preview of the image appears (if implemented).
• An upload progress bar or spinner shows.
• After a few seconds, a toast reads “Upload successful” (or the server confirms).

1. Verify on the backend that the file arrived with correct name, size, and MIME type.

3. Inject Error Conditions

4. Check UI Feedback and Logs

• Use adb logcat | grep -i upload to watch for any exceptions or warnings.
• Look for ActivityNotFoundException (missing picker handler) or SecurityException (URI access denied).
• Confirm that progress indicators are updated correctly and that the UI does not freeze (no ANR).
• Verify that error messages are user‑friendly and do not expose stack traces or internal paths.

5. Accessibility Spot‑Check

• Turn on TalkBack (Settings → Accessibility → TalkBack).
• Navigate to the upload button; ensure it announces its purpose and state.
• Verify that activating the button via TalkBack double‑tap works the same as a tap.
• Check contrast using a vision‑aid app or the Android Studio Layout Inspector.

6. Clean Up

• Remove pushed test files: adb shell rm /sdcard/Download/sample.jpg.
• Revoke any temporarily granted permissions if needed.

Repeating this checklist for each upload entry point (avatar, chat, document) gives you confidence that the core flows behave as expected before you invest in automation.

---

Automated Testing with Espresso and UIAutomator

Instrumented tests run on the device or emulator and can validate both UI interactions and underlying behavior. Espresso excels at testing within your app’s UI, while UIAutomator is needed for system dialogs like the native file picker.

1. Project Setup

Add the following dependencies to your app/build.gradle:

dependencies {
    androidTestImplementation "androidx.test.espresso:espresso-core:3.5.1"
    androidTestImplementation "androidx.test.uiautomator:uiautomator:2.2.0"
    androidTestImplementation "androidx.test:runner:1.5.2"
    androidTestImplementation "androidx.test:rules:1.5.0"
    // Optional: MockWebServer for backend simulation
    testImplementation "com.squareup.okhttp3:mockwebserver:4.12.0"
}

Create a test class under src/androidTest/java/com/example/app/UploadTest.kt.

2. Helper to Grant Permissions

@Before
fun grantPermissions() {
    // Grant storage permission for API 23+
    val context = ApplicationProvider.getApplicationContext()
    if (ContextCompat.checkSelfPermission(
            context,
            Manifest.permission.READ_EXTERNAL_STORAGE
        ) != PackageManager.PERMISSION_GRANTED) {
        GrantPermissionRule
            .grant(Manifest.permission.READ_EXTERNAL_STORAGE)
            .apply { }
    }
}

3. Espresso Test for Happy Path (Internal Picker)

If your app uses an internal file picker (e.g., a custom RecyclerView), you can test entirely with Espresso:

@Test
fun uploadImage_success() {
    // Launch the activity that contains the upload button
    val activityRule = ActivityScenarioRule(MainActivity::class.java)
    activityRule.scenario.onActivity { /* no extra setup needed */ }

    // Click the upload button
    onView(withId(R.id.btn_upload)).perform(click())

    // Verify that the custom picker opens (e.g., a RecyclerView with id rv_picker)
    onView(withId(R.id.rv_picker)).check(matches(isDisplayed()))

    // Choose the first item (assume it's a known test image)
    onView(withId(R.id.rv_picker))
        .perform(RecyclerViewActions.actionOnItemAtPosition<RecyclerView.ViewHolder>(0, click()))

    // Verify progress bar appears
    onView(withId(R.id.progress_upload)).check(matches(isDisplayed()))

    // Wait for upload to finish – we mock the backend with MockWebServer
    // Assume the app makes a POST to /upload and expects 200 OK
    // Here we just idle until a specific view appears (e.g., success toast)
    onView(withText(R.string.upload_success))
        .withEffectiveVisibility(Visibility.VISIBLE)
        .check(matches(isDisplayed()))
}

4. UIAutomator for System File Picker

When the app invokes Intent.ACTION_GET_CONTENT or Intent.ACTION_OPEN_DOCUMENT, the system picker appears. UIAutomator can interact with it:

@Test
fun uploadViaSystemPicker_success() {
    val device = UiDevice.getInstance(InstrumentationRegistry.getInstrumentation())

    // Launch the upload flow
    onView(withId(R.id.btn_upload)).perform(click())

    // Wait for the system picker to appear (title contains “Documents”)
    val pickerTitle = device.findObject(
        UiSelector().textContains("Documents")
    )
    assertTrue(pickerTitle.waitForExists(5000))

    // Navigate to Download folder
    val downloadFolder = device.findObject(
        UiSelector().text("Download")
    )
    downloadFolder.clickAndWaitForNewWindow()

    // Select the sample image (assume file name known)
    val sampleImg = device.findObject(
        UiSelector().textMatches("sample\\.jpg")
    )
    sampleImg.clickAndWaitForNewWindow()

    // Back in app – verify progress
    val progress = device.findObject(
        UiSelector().resourceId("com.example.app:id/progress_upload")
    )
    assertTrue(progress.waitForExists(10000))

    // Verify success toast
    val toast = device.findObject(
        UiSelector().className("android.widget.Toast")
    )
    assertTrue(toast.waitForExists(5000))
    assertTrue(toast.getText().contains("success"))
}

5. Handling Runtime Permissions in Tests

If the app requests permission at runtime, you can pre‑grant it using grantPermissionRule from androidx.test.ext.junit.rules:

@get:Rule
val permissionRule = GrantPermissionRule.grant(
    Manifest.permission.READ_EXTERNAL_STORAGE,
    Manifest.permission.CAMERA
)

6. Verifying Upload with MockWebServer

To avoid depending on a real backend, spin up a MockWebServer in @BeforeClass:

private lateinit var mockWebServer: MockWebServer

@BeforeClass
@JvmStatic
fun setUpServer() {
    mockWebServer = MockWebServer()
    mockWebServer.start()
    // Enqueue a 200 response with JSON indicating success
    mockWebServer.enqueue(
        MockResponse()
            .setResponseCode(200)
            .setBody("{\"status\":\"ok\"}")
    )
    // Optionally set the server URL in your app via manifest meta-data or DI
}

In your test, assert that the server received a request with the correct Content-Type and body (you can inspect mockWebServer.takeRequest()).

7. Running the Tests

Execute via Gradle:

./gradlew connectedAndroidTest   # runs all instrumented tests

Or target a specific class:

./gradlew connectedAndroidTest -Pandroid.testInstrumentationRunnerArguments.class=com.example.app.UploadTest

Automated tests give you repeatable regression guards for the happy path, basic error handling, and permission flows. However, they cannot easily simulate variable network conditions, background execution nuances, or the myriad of third‑party file picker apps that users may have installed. That’s where manual exploration and autonomous testing add value.

---

Automated Testing with Appium (Cross‑platform)

Appium lets you drive the Android UI from a test script written in Java, JavaScript, Python, etc., and works equally well for native apps, hybrid WebViews, and pure web apps accessed via Chrome.

1. Desired Capabilities

DesiredCapabilities caps = new DesiredCapabilities();
caps.setCapability("platformName", "Android");
caps.setCapability("deviceName", "Pixel_4_API_33");
caps.setCapability("appPackage", "com.example.app");
caps.setCapability("appActivity", ".MainActivity");
caps.setCapability("automationName", "UiAutomator2");
caps.setCapability("grantPermissions", true); // auto‑grant dangerous perms
AndroidDriver<MobileElement> driver = new AndroidDriver<>(
        new URL("http://localhost:4723/wd/hub"), caps);
driver.manage().timeouts().implicitlyWait(10, TimeUnit.SECONDS);

2. Triggering the Upload Flow

// Click the upload button
driver.findElement(By.id("btn_upload")).click();

// Wait for the system picker to appear (context NATIVE_APP)
new WebDriverWait(driver, 15)
        .until(ExpectedConditions.elementToBeClickable(By.xpath("//android.widget.TextView[@text='Documents']")));

// Navigate to Downloads
driver.findElement(By.xpath("//android.widget.TextView[@text='Download']")).click();

// Select the file
driver.findElement(By.xpath("//android.widget.TextView[@text='sample.jpg']")).click();

3. Handling the Return to App

After picking a file, the system returns control to your app. You can wait for a UI element unique to the upload screen (e.g., a progress bar):

new WebDriverWait(driver, 20)
        .until(ExpectedConditions.visibilityOfElementLocated(By.id("progress_upload")));

4. Verifying Upload via Network Inspection

Appium can retrieve network logs if you enable Chromedriver logging for WebView or use the adb logcat approach:

LogEntries logEntries = driver.manage().logs().get("performance");
for (LogEntry entry : logEntries) {
    Json json = Json.parse(entry.getMessage());
    // Look for a request to your upload endpoint and check status
}

Alternatively, use a proxy like mitmproxy to capture requests and assert that a multipart/form‑data POST with the correct file part was sent.

5. Testing Error Scenarios

• Permission denial: Revoke permission via adb shell pm revoke com.example.app android.permission.READ_EXTERNAL_STORAGE before starting the test, then assert that a permission dialog appears (driver.findElement(By.text("Allow access to photos, media, and files?"))).
• Network loss: Use adb shell svc wifi disable mid‑test, then verify that an error toast appears and the app offers a retry.
• Large file: Push a 50 MB video to the device, select it, and assert that either the client blocks it (shows size error) or the server returns 413 and the app displays the message.

6. Sample JavaScript (WebDriverIO) Test

describe('File upload flow', () => {
    it('should upload a picture from gallery', async () => {
        await $('~btn_upload').click(); // accessibility id
        await driver.waitUntil(
            async => (await $('android=new UiSelector().textContains("Documents")')).isExisting(),
            { timeout: 15000, interval: 500 }
        );
        await $('android=new UiSelector().text("Download")').click();
        await $('android=new UiSelector().text("sample.jpg")').click();

        await driver.waitUntil(
            async => (await $('~progress_upload')).isExisting(),
            { timeout: 20000, interval: 500 }
        );

        const toast = await $('android.widget.Toast');
        await expect(toast).toHaveTextContaining('success');
    });
});

Appium shines when you need to test across multiple device configurations or when your app includes a WebView where the file input is an HTML . In that case, you can bypass the native picker entirely by using driver.setFileDetector(new LocalFileDetector()) and then driver.findElement(By.css("input[type='file']")).sendKeys("/path/to/sample.jpg");.

---

Leveraging SUSA for Persona‑Driven Exploration

SUSA (SUSATest) is an autonomous QA agent that explores an app without pre‑written scripts. It injects a variety of user personas—each with distinct behavior patterns—into the app and monitors for crashes, ANRs, accessibility violations, security issues, and UX friction. When applied to file upload flows, SUSA can surface problems that scripted tests often miss because it does not follow a predetermined path; it tries combinations that real users might attempt out of curiosity, impatience, or confusion.

1. How SUSA Approaches an Upload Screen

When SUSA launches your app, it builds a state model of screens, buttons, and intents. For an upload screen it will:

• Tap the upload button repeatedly (simulating an impatient user).
• Attempt to open the file picker, then back out without selecting a file (curious user).
• Try to pick files from unexpected locations (e.g., the root of /sdcard, a hidden folder).
• Rotate the device, change font size, or enable TalkBack while the picker is open (accessibility persona).
• Simulate a loss of network mid‑picker (adversarial persona).
• Attempt to upload files with unusual names (../../evil.exe, files with Unicode control characters).

Each action is logged, and SUSA checks for:

• Crashes or ANRs (via tombstone logs).
• Dead buttons (UI elements that become unresponsive after a sequence).
• WCAG violations (missing labels, insufficient contrast).
• Security signals (file‑picker returning a content:// URI that the app tries to open as a File).
• UX friction (toast messages that are vague, progress bars that never complete).

2. Running SUSA via CLI

pip install susatest-agent
susatest run \
    --apk path/to/app-debug.apk \
    --personas curious impatient novice accessibility \
    --target upload \
    --output-dir ./susa-reports

The --target upload flag tells SUSA to prioritize screens that contain an upload button or an intent filter for ACTION_GET_CONTENT. You can omit the flag to let it explore the whole app; it will still hit upload flows as part of its exploration.

3. Cross‑Session Learning

Susa stores a knowledge base of visited UI states and dead ends. On a subsequent run it:

• Skips already‑verified happy paths to focus on new combinations.
• Prioritizes states that previously caused exceptions or long load times.
• Adapts its persona weights based on what yielded the most interesting results in earlier sessions (e.g., if the “impatient” persona repeatedly triggered a race condition, future runs will allocate more taps from that persona).

This learning loop means that over time Susa becomes better at finding edge‑case bugs that are rare but high‑impact, such as a crash that only occurs when a user picks a file, rotates the screen, and then quickly cancels the picker.

4. What SUSA Finds That Scripts Miss

Because SUSA treats the app as a black box and explores it with varied, semi‑randomized inputs, it complements both manual exploratory testing and automated regression suites.

---

Edge Cases That Surface Only in Production

Even with thorough lab testing, certain conditions only appear when the app runs in the wild. Below is a table of production‑only edge cases, the symptoms they cause, and the techniques you can use to detect or mitigate them.

To catch many of these issues in a lab, you can:

• Use the Android Emulator’s Extended Controls → Cellular to simulate network type changes and latency.
• Enable Developer options → Don’t keep activities to test state restoration after picker returns.
• Use adb shell cmd appops set READ_EXTERNAL_STORAGE ignore to revoke permissions at runtime.
• Leverage Firebase Test Lab or Google Play’s pre‑launch report to run on a matrix of real devices with varied locales and hardware configurations.

---

Checklist for Shipping File Upload Features

Before you mark an upload feature as “ready for release,” run through this concise checklist. It consolidates the most critical items from the matrix, manual steps, and automated guards.