Testing with Postman

In this guide we’ll validate a Flask image upload endpoint and exercise the application’s error handling with Postman and curl. You will learn how to:

Enforce allowed file extensions (PNG, JPG, JPEG) and intentionally reject GIFs because OpenCV’s decoder is unreliable for animated GIFs.
Verify file contents using imghdr and Pillow to prevent renamed non-image files from being accepted.
Require and validate a quality parameter (integer between 0 and 100).
Decode and re-encode images using OpenCV and return a validated JPEG binary response.
Return structured JSON errors with appropriate HTTP status codes for each failure case.

A presentation slide that says "Testing with Postman" on the left and shows a large blue "Demo" on a dark curved background on the right. The slide also has a small "© Copyright KodeKloud" in the bottom-left corner.

Upload route: validation overview

The upload route should perform these checks, in order:

Confirm the image file part exists and the filename is not empty.
Secure the filename and enforce allowed extensions: png, jpg, jpeg.
Read the file bytes once, then verify content:
- Use imghdr to detect the image signature in the bytes.
- Use Pillow (Image.verify()) for an additional sanity check.
Require a quality form parameter and validate it as an integer in [0, 100].
Decode the bytes with OpenCV, process and re-encode as JPEG with the requested quality.
Validate the processed output with Pillow before returning it as image/jpeg.
Return clear JSON errors and proper HTTP status codes for every failure branch.

The consolidated implementation below follows these steps and includes robust logging and error handling.

# routes.py (excerpt)
import io
import imghdr
import logging

from flask import request, jsonify, send_file
from werkzeug.utils import secure_filename
from PIL import Image, UnidentifiedImageError
import numpy as np
import cv2

logger = logging.getLogger(__name__)

def upload():
    try:
        # Basic request/file checks
        if 'image' not in request.files:
            logger.error('No image part in the request')
            return jsonify({'error': 'No image part in the request'}), 400

        image = request.files['image']

        if image.filename == '':
            logger.error('No image selected for uploading')
            return jsonify({'error': 'No image selected for uploading'}), 400

        # Secure the filename and check extension
        filename = secure_filename(image.filename)
        if '.' not in filename:
            logger.error('Invalid file extension: %s', filename)
            return jsonify({'error': 'Invalid file extension'}), 400

        ext = filename.rsplit('.', 1)[1].lower()
        allowed_extensions = {'png', 'jpg', 'jpeg'}
        if ext not in allowed_extensions:
            logger.error('Invalid file extension: %s', filename)
            return jsonify({'error': 'Invalid file extension'}), 400

        # Read file bytes once and reuse
        image_content = image.read()
        image.seek(0)  # reset if something else needs the file pointer

        # Validate content using imghdr (note: imghdr returns 'jpeg' for JPEGs)
        imghdr_type = imghdr.what(None, h=image_content)
        allowed_imghdr = {'jpeg', 'png'}
        if imghdr_type not in allowed_imghdr:
            logger.error('Invalid image file content for: %s', filename)
            return jsonify({'error': 'Invalid image file'}), 400

        # Additional validation with Pillow
        try:
            img = Image.open(io.BytesIO(image_content))
            img.verify()  # verify that it is an image
        except (UnidentifiedImageError, OSError) as e:
            logger.error('Invalid image file: %s', e)
            return jsonify({'error': 'Invalid image file'}), 400

        # Require quality parameter
        if 'quality' not in request.form:
            logger.error('Quality parameter is missing')
            return jsonify({'error': 'Quality parameter is required'}), 400

        quality = request.form.get('quality', type=int)
        if quality is None or quality < 0 or quality > 100:
            logger.error('Invalid quality value: %s', quality)
            return jsonify({'error': 'Quality must be an integer between 0 and 100'}), 400

        # Decode with OpenCV
        img_array = np.frombuffer(image_content, np.uint8)
        img_cv = cv2.imdecode(img_array, cv2.IMREAD_UNCHANGED)
        if img_cv is None:
            logger.error('Failed to decode image: %s', filename)
            return jsonify({'error': 'Failed to decode image'}), 400

        # Re-encode to JPEG with requested quality
        success, buffer = cv2.imencode('.jpg', img_cv, [int(cv2.IMWRITE_JPEG_QUALITY), quality])
        if not success:
            logger.error('Failed to encode image: %s', filename)
            return jsonify({'error': 'Failed to process image'}), 400

        # buffer is a 1-D numpy array of uint8 bytes; convert to bytes for BytesIO
        img_io = io.BytesIO(buffer.tobytes())

        # Validate processed image using Pillow
        try:
            processed_img = Image.open(img_io)
            processed_img.verify()
        except (UnidentifiedImageError, OSError) as e:
            logger.error('Failed to process image: %s', e)
            return jsonify({'error': 'Failed to process image'}), 400

        img_io.seek(0)
        return send_file(img_io, mimetype='image/jpeg')

    except Exception as e:
        logger.exception('An unexpected error occurred: %s', e)
        return jsonify({'error': 'An unexpected error occurred. Please try again later.'}), 500

If you must accept GIFs, decode them with Pillow (e.g., iterate frames) and convert a chosen frame(s) to an image OpenCV can process. OpenCV’s imdecode is not suitable for animated GIF decoding.

How to test

Postman (form-data)
- URL: POST http://127.0.0.1:5000/upload
- Body (form-data)
  - Key: image — File: DSC08804.JPG
  - Key: quality — Text: 100
curl example (uploads a JPEG at quality 100):

curl -X POST \
  -F "image=@./samples/DSC08804.JPG" \
  -F "quality=100" \
  http://127.0.0.1:5000/upload --output result.jpg

Common test cases and expected responses

Test case	HTTP Status	JSON response
Missing file part	400	`{"error":"No image part in the request"}`
Empty filename	400	`{"error":"No image selected for uploading"}`
Disallowed extension (including GIF)	400	`{"error":"Invalid file extension"}`
Renamed non-image file (e.g., text renamed .png)	400	`{"error":"Invalid image file"}`
Missing `quality`	400	`{"error":"Quality parameter is required"}`
Invalid `quality` (non-integer or out of range)	400	`{"error":"Quality must be an integer between 0 and 100"}`
Failed to decode with OpenCV (corrupt or unsupported)	400	`{"error":"Failed to decode image"}`
Unexpected server error	500	`{"error":"An unexpected error occurred. Please try again later."}`

Additionally, the same JSON examples are shown here as sample responses:

Missing file:

{ "error": "No image part in the request" }

Empty filename:

{ "error": "No image selected for uploading" }

Disallowed extension:

{ "error": "Invalid file extension" }

Wrong file content:

{ "error": "Invalid image file" }

Missing or invalid quality parameter:

{ "error": "Quality parameter is required" }

{ "error": "Quality must be an integer between 0 and 100" }

Failed to decode with OpenCV:

{ "error": "Failed to decode image" }

Example server logs

INFO:werkzeug:127.0.0.1 - - [20/Nov/2024 20:59:02] "POST /upload HTTP/1.1" 200 -
ERROR:app.routes:Failed to decode image: coolguy.gif
INFO:werkzeug:127.0.0.1 - - [20/Nov/2024 20:59:22] "POST /upload HTTP/1.1" 400 -
ERROR:app.routes:Invalid file extension: test.txt
INFO:werkzeug:127.0.0.1 - - [20/Nov/2024 20:59:22] "POST /upload HTTP/1.1" 400 -
ERROR:app.routes:Invalid image file content for: test.png
INFO:werkzeug:127.0.0.1 - - [20/Nov/2024 21:03:48] "POST /upload HTTP/1.1" 400 -

Why multi-layer validation matters

File extension checks provide a fast fail for obvious bad uploads.
imghdr inspects raw file bytes and prevents trivial bypass by renaming files.
Pillow’s Image.verify() ensures the bytes represent a valid image file structure.
OpenCV is used for image processing and re-encoding, but it requires decodable bytes — hence the prior validations.
Together, these layers improve security and robustness while producing deterministic failure responses for clients.

Next steps

With the backend validated and robust error handling in place, you can:

Build a React front-end to consume this API and show upload progress and errors.
Add rate limiting and size limits to prevent abuse.
Implement background processing (e.g., Celery) for heavy image transformations.
If GIF support is required, use Pillow to extract frames and convert frames to an OpenCV-friendly format.

References and further reading

Thank you for following this lesson.

Course Introduction

Introduction to AI-Assisted Development

Planning Phase

Development Phase - Backend

Development Phase - Frontend

Project Completion

Testing with Postman

Upload route: validation overview

How to test

Common test cases and expected responses

Example server logs

Why multi-layer validation matters

Next steps

Watch Video

​Upload route: validation overview

​How to test

​Common test cases and expected responses

​Example server logs

​Why multi-layer validation matters

​Next steps

Watch Video

Upload route: validation overview

How to test

Common test cases and expected responses

Example server logs

Why multi-layer validation matters

Next steps