Skip to main content

HTTP REQUESTS

Multipart Requests

Upload files and handle complex form data using Karate's multipart keywords with automatic Content-Type handling and encoding.

Troubleshooting Multipart Uploads

Multipart file uploads can be tricky. If you encounter issues, create a working cURL command first to verify the server's expectations, then translate it to Karate. This isolates whether the issue is with Karate syntax or server requirements.

Benefits of Multipart Requests​

  • Automatic encoding: Karate handles multipart encoding and Content-Type headers
  • File uploads simplified: Upload files without complex HTTP client code
  • Mixed content support: Combine text fields, JSON, and files in one request
  • Bulk operations: Upload multiple files or set multiple fields in one step

Single Field Operations​

multipart field - Form Fields​

Add text fields to multipart requests:

Feature: Multipart form fields

Scenario: Basic multipart form
Given url baseUrl
And path 'upload'
And multipart field description = 'Profile photo upload'  # Text field
And multipart field category = 'avatar'
And multipart file photo = { read: 'profile.jpg', filename: 'user-photo.jpg' }  # File field
When method post
Then status 200
Key Points
  • Use multipart field for text, numbers, or JSON data in forms
  • Combine with multipart file for file uploads
  • Content-Type is automatically set to multipart/form-data

Multiple Form Fields​

Feature: Multiple form fields

Scenario: Form with various field types
Given url baseUrl
And path 'upload'
And multipart field userId = 123  # Number field
And multipart field metadata = { type: 'image', processed: false }  # JSON object as field
And multipart field tags = ['profile', 'avatar']  # Array as field
And multipart file photo = { read: 'profile.jpg', filename: 'user-photo.jpg' }
When method post
Then status 200

multipart file - File Uploads​

Upload files in multipart requests:

Feature: File uploads

Scenario: Simple file upload
Given url baseUrl
And path 'documents/upload'
And multipart file document = { read: 'contract.pdf', filename: 'contract.pdf' }
And multipart field description = 'Legal contract'
When method post
Then status 201
And match response.documentId == '#string'

File Upload with Metadata​

Configure filename and content type for uploaded files:

Feature: File upload with metadata

Scenario: Custom filename and content type
Given url baseUrl
And path 'images/upload'
And multipart file image = { read: 'photo.jpg', filename: 'profile-photo.jpg', contentType: 'image/jpeg' }  # Custom filename and MIME type
And multipart field alt = 'User profile photo'
And multipart field tags = ['profile', 'user', 'photo']
When method post
Then status 200

multipart entity - Content Without Field Names​

Use for multipart content that does not have field names (multipart/related):

Feature: Multipart entities

Scenario: Multipart/related content
Given url baseUrl
And path 'documents/complex'
And multipart entity read('metadata.json')  # No field name
And multipart field description = 'Document with metadata'
And multipart file document = { read: 'report.pdf', filename: 'report.pdf' }
And header Content-Type = 'multipart/related'  # Override default
When method post
Then status 201

Bulk Operations​

multipart fields - Multiple Form Fields​

Set multiple form fields at once using JSON:

Feature: Multiple multipart fields

Scenario: Bulk multipart field assignment
Given url baseUrl
And path 'upload/batch'
* multipart fields { description: 'Batch upload', category: 'documents', userId: 123 }  # Set multiple fields at once
And multipart file doc1 = { read: 'file1.pdf', filename: 'document1.pdf' }
And multipart file doc2 = { read: 'file2.pdf', filename: 'document2.pdf' }
When method post
Then status 202

Complex Field Data​

Feature: Nested field data

Scenario: Fields with nested JSON
Given url baseUrl
And path 'upload/batch'
* multipart fields { description: 'Batch upload', tags: ['important', 'legal'], metadata: { processingMode: 'async', notifyOnComplete: true } }
And multipart file document = { read: 'file.pdf', filename: 'doc.pdf' }
When method post
Then status 202

multipart files - Multiple File Uploads​

Upload multiple files at once using JSON:

Feature: Multiple file uploads

Scenario: Bulk file upload
Given url baseUrl
And path 'media/upload'
* def fileUploads = {}
* set fileUploads.photo1 = { read: 'image1.jpg', filename: 'photo1.jpg', contentType: 'image/jpeg' }  # Field name: photo1
* set fileUploads.photo2 = { read: 'image2.png', filename: 'photo2.png', contentType: 'image/png' }  # Field name: photo2
* set fileUploads.document = { read: 'info.pdf', filename: 'information.pdf' }
And multipart files fileUploads  # Upload all files at once
And multipart field albumName = 'Vacation Photos'
When method post
Then status 200

Dynamic File Lists​

Build file upload objects dynamically using JavaScript:

Feature: Dynamic file uploads

Scenario: Generate file list dynamically
Given url baseUrl
And path 'batch/upload'
* def fileList = ['doc1.pdf', 'doc2.pdf', 'doc3.pdf']
* def buildUploads =
  """
  function(files) {
    var uploads = {};
    files.forEach(function(filename, index) {
      var key = 'file' + (index + 1);
      uploads[key] = { read: filename, filename: 'upload-' + filename, contentType: 'application/pdf' };
    });
    return uploads;
  }
  """
* def uploads = buildUploads(fileList)
And multipart files uploads
When method post
Then status 200

Advanced Patterns​

Multiple Content Types​

Upload different file types in a single request:

Feature: Mixed content types

Scenario: Upload various file types
Given url baseUrl
And path 'content/upload'
And multipart field metadata = { title: 'Mixed content', created: '2025-01-01' }
And multipart field description = 'Upload with various file types'
And multipart file image = { read: 'chart.png', filename: 'chart.png', contentType: 'image/png' }
And multipart file data = { read: 'data.csv', filename: 'data.csv', contentType: 'text/csv' }
And multipart file config = { read: 'config.json', filename: 'config.json', contentType: 'application/json' }
When method post
Then status 200

Large Files and Binary Data​

Handle large files and binary uploads with timeouts:

Feature: Binary and large file uploads

Scenario: Binary file upload
Given url baseUrl
And path 'files/binary'
And multipart file binary = { read: 'data.zip', filename: 'archive.zip', contentType: 'application/zip' }
And multipart field checksum = 'sha256:abc123...'
When method post
Then status 200

Large File Uploads​

Feature: Large file handling

Scenario: Upload large file with timeout
Given url baseUrl
And path 'files/large'
* configure readTimeout = 120000  # 2 minutes for large files
And multipart file largefile = { read: 'large-dataset.csv', filename: 'dataset.csv' }
And multipart field processing = 'async'
When method post
Then status 202  # Accepted for async processing
Common Gotchas
  • Content-Type: Automatically set to multipart/form-data unless overridden with header keyword
  • File paths: Use classpath: prefix for files in src/test/resources
  • Field names: multipart entity does not use field names, all other multipart keywords do
  • Null values ignored: JSON fields with null values are automatically skipped

Next Steps​

Master multipart requests and continue with:

On This Page