Testing a file upload is more than selecting a document and checking whether a success message appears. This reusable checklist helps developers and QA teams test file size limits, extension and MIME-type validation, browser behavior, progress states, retries, failure handling, and security controls before an upload flow reaches production.
Overview
A reliable upload test covers the complete path from the browser file picker to temporary storage, processing, and final persistence. A file may pass one layer and fail another: the browser can report one MIME type, the filename can use a misleading extension, and the server or storage provider can apply a different size limit. Test each layer independently and then test the full workflow.
Before testing, write down the expected behavior for each supported file category. Define the allowed extensions, the content types you expect to receive, the maximum file size, whether multiple files are supported, and what users should see when validation fails. Also record whether uploads are sent through your application server or directly to storage with a signed upload URL. These decisions affect where validation, authorization, logging, and cleanup must occur.
For a broader security review, use the file upload abuse prevention checklist. If uploaded images or documents may contain personal information, review what to strip from EXIF and file metadata as part of the test plan.
Checklist by scenario
1. Basic valid uploads
- Upload one valid file for every supported type, such as an image, document, archive, or text file.
- Confirm the visible filename, file size, file type, and upload status are correct.
- Refresh or reopen the destination and verify that the stored file can be retrieved or processed as intended.
- Check that the server response is handled correctly for both success and application-level errors.
2. Extension and MIME-type validation
Test extension checks and MIME-type checks as separate cases. Try a permitted extension with unexpected content, an unsupported extension, an uppercase extension, and a filename containing multiple dots. Do not treat the browser-provided MIME type as proof of the file's contents; it is useful input for validation but should not be the only security control.
- Test filenames such as
report.PDF,photo.jpeg, and names with spaces or non-ASCII characters. - Test a file whose extension does not match its actual content.
- Confirm that rejected files receive a clear, non-sensitive error message.
- Verify that validation also runs on the server or upload service, not only in client-side JavaScript.
3. Size-limit testing
Test files below the limit, exactly at the limit, slightly above it, and substantially above it. Use the same units and rounding rules in the interface, API, and backend configuration so that a user does not see a file described as valid in one place and rejected in another.
- Confirm that oversized files are rejected before unnecessary processing or storage.
- Check whether the browser receives a useful response when a proxy, application server, or storage service rejects the request.
- Test a zero-byte file and a file that grows or changes while it is being selected, where the workflow permits this.
- Record the effective limit at every layer, including request-body, application, and storage limits.
4. Multiple files, ordering, and removal
Test selecting files in one action, adding files in several actions, removing a pending file, and changing the order before submission. Confirm that a failed item does not silently block valid items unless that is the intended behavior. For a detailed implementation checklist, see how to build a multi-file upload flow with ordering, removal, and retry.
5. Network and retry behavior
Interrupt an upload by disabling the network, closing a connection, navigating away, or allowing a request to time out. Restore connectivity and test the retry path. A retry should not create duplicate records or duplicate stored objects. Include an idempotency strategy or an equivalent duplicate-detection rule where the workflow requires it. The guide to handling upload retries without duplicates provides useful cases to add to a QA plan.
6. Large files and progress states
Use a file large enough to keep the upload active while you observe the interface. Check the initial, active, paused or interrupted, completed, and failed states. Progress should not jump backward without explanation, remain permanently active after a response, or report completion before the server confirms success. Also test a slow connection and a device with limited available memory.
For user-facing progress behavior, compare your implementation against the edge cases in upload progress bar testing.
7. Browser and input variations
Test the browsers and operating systems your application supports. Include drag-and-drop if available, the standard file picker, keyboard navigation, mobile selection, canceling the picker, and selecting the same file again after a failed attempt. Browser file inputs can differ in how they expose names, types, directories, and repeated selections; use the cross-browser file input checklist when expanding coverage.
8. Folder and directory uploads
If the interface supports folders, test empty directories, nested folders, duplicate names in different directories, hidden files, and a mixture of supported and unsupported files. Confirm whether relative paths are preserved and whether the server normalizes them safely. Folder support should never allow a client-supplied path to determine an unsafe storage location. See how to support folder uploads in the browser for additional cases.
What to double-check
Validation location: Client-side checks improve feedback but can be bypassed. Treat server-side or storage-side validation as authoritative.
Storage names and paths: Do not use an untrusted filename as a direct filesystem path. Normalize names, prevent path traversal, and consider generating an internal identifier while retaining a safe display name.
Access control: Confirm that a user cannot retrieve another user's upload by changing an identifier or URL. Test both authenticated and unauthenticated requests, including expired sessions and revoked signed URLs.
Upload architecture: If you use direct-to-storage uploads, verify that the signed request restricts the intended object, method, size, content type, and expiration according to your design. If uploads pass through your application, check request limits, timeouts, and resource usage. Compare the trade-offs in signed upload URLs versus proxy uploads.
Temporary data: Force failures after a file is received but before processing completes. Confirm that abandoned parts, temporary files, and failed records are cleaned up according to your retention design. The temporary storage checklist can help identify overlooked cleanup paths.
Logging: Log enough information to trace failures, such as a request identifier, outcome, size category, and validation reason. Avoid logging file contents, credentials, signed URLs, or sensitive personal data.
Common mistakes
- Testing only a small image: This misses size limits, slow transfers, timeouts, and processing failures.
- Trusting the extension: A filename is user-controlled and does not establish the file's actual content.
- Relying only on the browser: Client-side validation can be skipped or modified, so repeat important checks on a trusted backend or service.
- Checking only the HTTP status: A request can receive a transport-level success while the application reports a failed validation or processing result.
- Ignoring partial uploads: Interrupted multipart or chunked uploads may leave storage objects and database records behind.
- Making errors too vague: “Upload failed” gives users and testers little direction. Explain whether the issue is size, type, authorization, network, or temporary service availability without exposing internal details.
- Forgetting accessibility: Test keyboard access, focus movement, labels, status announcements, and error association. A visually clear progress indicator is not sufficient if assistive technology cannot interpret it.
When to revisit
Keep this checklist with the upload flow's test plan and revisit it whenever an underlying input changes. Run a focused regression after changing accepted file types, maximum sizes, processing libraries, storage providers, proxy settings, authentication, signed URL rules, or retry logic. Repeat browser coverage when the interface changes from a file picker to drag-and-drop, mobile capture, folder selection, or a multi-file component.
Before a seasonal planning cycle or a period when usage is expected to change, review limits, quotas, temporary-file cleanup, monitoring, and failure alerts. When workflows or tools change, create at least one test for the new path and one test that proves the old path still fails safely. Finally, retain representative test files that are safe to share, label them by expected result, and document the exact size, extension, content type, and scenario for each. That small test library makes future upload testing faster, more repeatable, and easier to audit.
