tessl/pypi-vcrpy

Automatically mock your HTTP interactions to simplify and speed up testing

Overview

Eval results

Files

Record Modes

Name: tessl/pypi-vcrpy
Author: tessl

Recording behavior configuration that determines when HTTP interactions are recorded versus replayed from existing cassettes. Record modes provide fine-grained control over VCR.py's recording strategy for different testing scenarios.

Capabilities

RecordMode Enum

Enumeration defining when VCR will record HTTP interactions to cassettes.

class RecordMode(str, Enum):
    """
    Configures when VCR will record to the cassette.
    
    Can be used either as enum values (vcr.mode.ONCE) or as strings ("once").
    """
    ALL = "all"
    ANY = "any"
    NEW_EPISODES = "new_episodes" 
    NONE = "none"
    ONCE = "once"

Mode Alias

# Alias for RecordMode for backward compatibility
mode = RecordMode

Record Mode Behaviors

ONCE Mode

Value: "once"
Behavior: Records the first set of requests, then replays them on subsequent runs. Attempting to add new episodes fails.

import vcr

# Using enum
my_vcr = vcr.VCR(record_mode=vcr.mode.ONCE)

# Using string
my_vcr = vcr.VCR(record_mode="once")

@my_vcr.use_cassette('test.yaml')
def test_once_mode():
    # First run: records all HTTP interactions
    # Subsequent runs: replays recorded interactions
    # New requests not in cassette will cause test failure
    pass

NEW_EPISODES Mode

Value: "new_episodes"
Behavior: Replays existing interactions from cassette, but records any new requests not found in the cassette.

my_vcr = vcr.VCR(record_mode=vcr.mode.NEW_EPISODES)

@my_vcr.use_cassette('test.yaml')
def test_new_episodes():
    # Existing requests: replayed from cassette
    # New requests: recorded and added to cassette
    # Useful for evolving APIs or adding new test coverage
    pass

ALL Mode

Value: "all"
Behavior: Records every request, regardless of whether it already exists in the cassette.

my_vcr = vcr.VCR(record_mode=vcr.mode.ALL)

@my_vcr.use_cassette('test.yaml')
def test_all_mode():
    # Every HTTP request is recorded
    # Cassette grows with each test run
    # Useful for debugging or capturing request variations
    pass

NONE Mode

Value: "none"
Behavior: No requests are recorded. Only existing cassette interactions are replayed.

my_vcr = vcr.VCR(record_mode=vcr.mode.NONE)

@my_vcr.use_cassette('test.yaml')
def test_none_mode():
    # No recording occurs
    # Only existing cassette interactions available
    # New requests will cause UnhandledHTTPRequestError
    # Useful for ensuring tests don't make unexpected requests
    pass

ANY Mode

Value: "any"
Behavior: Special recording mode with specific matching behavior.

my_vcr = vcr.VCR(record_mode=vcr.mode.ANY)

@my_vcr.use_cassette('test.yaml') 
def test_any_mode():
    # Special matching behavior
    # Consult VCR.py documentation for specific ANY mode semantics
    pass

Usage Patterns

Development Workflow

import vcr

# During initial development - record all interactions
dev_vcr = vcr.VCR(record_mode=vcr.mode.ALL)

# For stable tests - use recorded interactions only
stable_vcr = vcr.VCR(record_mode=vcr.mode.ONCE)

# When adding new features - record new requests
incremental_vcr = vcr.VCR(record_mode=vcr.mode.NEW_EPISODES)

# For CI/production - ensure no unexpected requests  
strict_vcr = vcr.VCR(record_mode=vcr.mode.NONE)

Dynamic Mode Selection

import os
import vcr

# Select mode based on environment
mode = os.environ.get('VCR_RECORD_MODE', 'once')
my_vcr = vcr.VCR(record_mode=mode)

@my_vcr.use_cassette('test.yaml')
def test_with_env_mode():
    # Mode controlled by environment variable
    # VCR_RECORD_MODE=all pytest test_file.py
    # VCR_RECORD_MODE=none pytest test_file.py
    pass

Per-Test Mode Override

base_vcr = vcr.VCR(record_mode=vcr.mode.ONCE)

@base_vcr.use_cassette('test.yaml', record_mode=vcr.mode.NEW_EPISODES)
def test_with_mode_override():
    # Override the base VCR's record mode for this specific test
    # Useful for individual test customization
    pass

Error Scenarios

ONCE Mode with New Requests

When using ONCE mode, attempts to make requests not in the cassette will raise an exception:

import vcr

@vcr.use_cassette('existing.yaml', record_mode='once')
def test_new_request_fails():
    # If existing.yaml doesn't contain this request:
    # Raises: CannotOverwriteExistingCassetteException
    response = requests.get('http://new-endpoint.com')

NONE Mode with Missing Requests

When using NONE mode, requests not in the cassette will raise an error:

@vcr.use_cassette('partial.yaml', record_mode='none')
def test_missing_request_fails():
    # If partial.yaml doesn't contain this request:
    # Raises: UnhandledHTTPRequestError
    response = requests.get('http://missing-endpoint.com')

Install with Tessl CLI