File Uploads and Form Bodies

Overview

Many APIs don't take JSON. A login or OAuth token endpoint may expect an HTML-style form. An avatar or document upload expects a multipart form with a file in it. An image endpoint may expect the raw bytes of a PNG as the whole request body. In Shift-Left Studio, a REST test's request body can now be any of these, alongside the JSON or text body you already use.

You choose the body type in the test editor, add form fields and attach files, and Studio sends exactly those bytes wherever the test runs: the Run button, test run packs and schedules, workflows, data-driven iterations, load tests, and the Shift-Left Agent (local runner).

Tests you already have are not affected. A test that sent JSON before sends the same bytes now. Endpoints imported from an OpenAPI or Swagger file that accept only forms, and Postman requests with form or file bodies, now send those bodies correctly without extra work.

Key concepts

Before you begin

• The test must be a REST test. SOAP, GraphQL, JSON-RPC and WebSocket-RPC tests do not use these body types.
• Save the test at least once before you attach a file. A file belongs to a project, so an unsaved test has nowhere to store it.
• Have the file you want to upload ready on your computer. The default size limit is 10 MB per file.

Step 1 — Open the request body

1. Open the test in the test editor.
2. On the Request tab, scroll to Request Body.
3. Above the body you'll see a row of buttons: Auto, JSON / text, Form (url-encoded), Multipart form and File.

The Auto button shows what it resolves to, for example Auto — a multipart form. Under the buttons, a line explains the choice, for example Sent as a multipart form because the endpoint accepts only multipart/form-data.

Step 2 — Choose a body type

Leave Auto selected unless you need to override it. Auto picks, in this order:

1. The body type set in the test's own Content-Type header, when you set one deliberately.
2. A form, when the endpoint's specification documents only form bodies (a multipart form if multipart is among them).
3. A form, when the test has form fields (a multipart form if any field is a file).
4. File, when a file is chosen for the whole body.
5. JSON / text otherwise.

To override it, click one of the other buttons.

Note: A Content-Type you set yourself is respected. For example, a negative test that deliberately sends text/plain to an upload endpoint, to check that it answers 415, stays exactly as written. The one exception is the application/json header that test generation adds to every REST test: on an endpoint that accepts only forms, Studio treats it as a default rather than a choice.

Step 3 — Add form fields (url-encoded or multipart)

When you pick Form (url-encoded) or Multipart form, the body editor becomes a table of fields.

1. Click Add field to add a text field.
2. In a multipart form, click Add file field to add a file field.
3. For each row, type the Field name, pick the Text or File kind, and enter the value or choose the file.
4. Click Remove on a row to delete it.

Things to know about form values:

• Values accept dynamic values. Type {{ in a value to pick one, the same as anywhere else in a test.
• A value that is an object or a list is sent as JSON text. It is never sent as [object Object].
• A list of plain values is sent as the same field repeated, for example tag=a&tag=b.
• The same field name can appear more than once, which is how you send several files under one name.
• A url-encoded form cannot carry a file. If a row is a file, the editor warns A url-encoded form cannot carry a file — use a multipart form.

Tip: If the test already has a JSON body when you switch to a form, Studio moves the JSON fields into the table for you. If it did not, the editor lists them and offers Move them into this table.

Form fields are the test's form parameters. While the form editor is shown, the Parameters table hides those rows and shows Form fields are edited under Request Body below, so there is one place to edit them.

Step 4 — Attach a file

In a file field (multipart), or after you pick File for the whole body:

1. Click Choose file… and pick the file on your computer. Studio uploads it to the project straight away and shows its name, type and size.
2. To reuse a file already stored in the project, click Use an uploaded file and choose it from the list.
3. To swap the file, click Replace…. To clear it, click Remove.
4. Save the test.

When you pick File for the whole body, the file's type becomes the request's Content-Type unless you set one under Headers.

Important: A test stores only a reference to the file, never its contents. Copying, exporting or opening a test is not slowed down by the file. Run records describe the upload (name, file name, type and size) without storing its bytes.

Step 5 — Run the test and check what was sent

1. Click Run.
2. In the results, open the Request tab to see how the body was sent. A file part is described, for example name="avatar"; filename="me.png" (image/png, 48213 byte(s)).
3. Open the Logs tab to see any notes about the body, such as a file field that was sent without a file.

Importing forms and files

OpenAPI and Swagger

There's nothing extra to do. Endpoints keep their documented content types. Tests generated for an endpoint that accepts only forms are sent as forms. A field typed as a binary string (OpenAPI 3 format: binary) or as a file (Swagger 2 type: file) is sent as a file part. Until you choose a real file, such a field is sent as a small placeholder (see below).

Postman collections

Postman form-data, x-www-form-urlencoded and binary bodies are imported, and the endpoint documents them. A Postman collection records only the file's path on the computer of the person who exported it, never the file itself. So each imported file field arrives named but empty:

• The import summary says N file upload(s) need a file chosen.
• The test editor shows No file chosen (the import named "invoice.pdf") until you pick the file.
• Re-importing the collection keeps any file you have chosen since.

See Postman collection import.

What happens when a file is missing

Managing stored files

• Uploading the same file twice gives you the same stored file.
• A file that a test still uses cannot be deleted. The refusal names the tests that use it.
• Deleting a project deletes its stored files.

Understanding the limits

Troubleshooting

Best practices

• Leave the body on Auto unless you need a specific encoding. Auto follows the endpoint's documentation.
• Keep one stored copy of each test file and reuse it with Use an uploaded file.
• Keep negative upload tests (missing file, wrong type) as separate tests so their intent is clear.
• Use small, representative files. Large files slow down load tests and runs without testing more.

FAQ

Do my existing JSON tests change? No. A test that sent JSON before sends exactly the same bytes.

Does the Shift-Left Agent (local runner) send the files? Yes. It downloads each file from the server it is signed in to, then sends it.

Can the assistant attach a file for me? No. Choose files in the test editor. The assistant works with references, never file contents.

Can I use dynamic values in form fields? Yes, in text fields. Type {{ to pick one.

Related articles

• Test cases: open, edit and save
• Import API definitions
• Postman collection import
• Assertions, results and custom checks

For administrators (self-hosted installations)