pytest-flask

A pytest plugin that provides a comprehensive set of fixtures and utilities for testing Flask web applications. This plugin extends pytest's testing capabilities with Flask-specific fixtures including test client creation, live server functionality, request context management, and specialized assertion helpers.

Package Information

• Package Name: pytest-flask
• Package Type: pytest plugin
• Language: Python
• Installation: pip install pytest-flask

Core Imports

The plugin automatically registers itself with pytest through the pytest11 entry point defined in setup.cfg. No manual imports are required in test files - just install the package and the fixtures become available.

Entry Point Registration (setup.cfg):

[options.entry_points]
pytest11 = 
    flask = pytest_flask.plugin

This registration makes all fixtures available automatically when pytest runs. The plugin also registers custom pytest markers and command line options through plugin hooks:

Registered Markers:

• @pytest.mark.app(options) - pass options to your application factory
• @pytest.mark.options - app config manipulation

Command Line Options Added:

• --start-live-server / --no-start-live-server - control automatic server startup
• --live-server-wait - set server startup timeout
• --live-server-clean-stop / --no-live-server-clean-stop - control shutdown behavior
• --live-server-host / --live-server-port - configure server address

For application factory pattern:

import pytest
from myapp import create_app

@pytest.fixture
def app():
    app = create_app()
    app.config['TESTING'] = True
    return app

Basic Usage

import pytest
from flask import url_for, jsonify
from myapp import create_app

@pytest.fixture
def app():
    """Application factory fixture - required by pytest-flask"""
    app = create_app()
    app.config['TESTING'] = True
    app.config['SECRET_KEY'] = 'test-secret'
    
    # Simple test route
    @app.route('/ping')
    def ping():
        return jsonify(ping='pong')
    
    return app

def test_ping_endpoint(client):
    """Test using the test client fixture"""
    response = client.get(url_for('ping'))
    assert response.status_code == 200
    assert response.json == {'ping': 'pong'}

def test_with_live_server(live_server):
    """Test using the live server fixture"""
    import requests
    response = requests.get(live_server.url('/ping'))
    assert response.status_code == 200
    assert response.json() == {'ping': 'pong'}

@pytest.mark.options(debug=True, testing=False)
def test_with_custom_config(app, config):
    """Test using configuration markers and fixtures"""
    assert app.debug is True
    assert config['TESTING'] is False

Architecture

pytest-flask provides testing infrastructure through three main layers:

• Plugin Integration: Registers with pytest via entry points, providing automatic fixture loading
• Fixture System: Core fixtures (client, config, live_server) with automatic Flask app detection
• Enhanced Testing: JSON response helpers, request context management, and configuration markers

The plugin requires users to define an app fixture that returns a Flask application instance, then automatically provides dependent fixtures for comprehensive Flask application testing.

Capabilities

Test Client Fixtures

Provides Flask test client instances and utilities for HTTP request testing. Includes standard test client access and class-based test integration.

@pytest.fixture
def client(app): ...

@pytest.fixture  
def client_class(request, client): ...

Test Client

Application Configuration

Access and manipulation of Flask application configuration during tests, including runtime config changes via markers.

@pytest.fixture
def config(app): ...

# Marker usage
@pytest.mark.options(debug=True, testing=False)
def test_function(): ...

Configuration

Live Server Testing

Runs Flask applications in separate processes for integration testing with real HTTP requests and external service interaction.

@pytest.fixture(scope=_determine_scope)
def live_server(request, app, pytestconfig): ...

class LiveServer:
    def start(self): ...
    def stop(self): ...  
    def url(self, url=""): ...

Live Server

HTTP Accept Headers

Pre-configured accept header fixtures for testing content negotiation and API responses with different MIME types.

@pytest.fixture
def accept_json(request): ...

@pytest.fixture
def accept_jsonp(): ...

@pytest.fixture(params=["application/json", "text/html"])
def accept_mimetype(request): ...

@pytest.fixture(params=["*", "*/*"])
def accept_any(request): ...

Accept Headers

Automatic Test Enhancements

pytest-flask automatically enhances test responses and provides automatic request context management without requiring explicit setup.

class JSONResponse:
    """
    Mixin with testing helper methods for JSON responses.
    Automatically applied to all Flask test responses.
    """
    def __eq__(self, other):
        """Allow direct comparison with HTTP status codes"""
        
def _push_request_context(request):
    """
    Automatic fixture that pushes Flask request context during tests.
    Enables url_for, session, and other Flask utilities in tests.
    """

def _configure_application(request, monkeypatch):
    """
    Automatic fixture that applies @pytest.mark.options decorations
    to Flask application configuration.
    """

The plugin automatically registers pytest markers and configures test environments, eliminating the need for manual setup in most cases.