📘 Snapshot Testing: Comparing Outputs

🎯 Introduction

Welcome to the fascinating world of snapshot testing! 🎉 Have you ever wished you could take a “photo” of your code’s output and automatically check if it changes unexpectedly? That’s exactly what snapshot testing does!

Imagine you’re a chef 👨‍🍳 who perfected a recipe. You take a photo of the final dish. Next time you cook, you compare your new dish with the photo to ensure it looks exactly the same. That’s snapshot testing in a nutshell!

By the end of this tutorial, you’ll be confidently using snapshot testing to catch unexpected changes in your Python applications. Let’s dive in! 🏊‍♂️

📚 Understanding Snapshot Testing

🤔 What is Snapshot Testing?

Snapshot testing is like having a photographic memory for your code’s output 📸. Think of it as creating a “golden copy” of what your code produces, then automatically comparing future outputs against this reference.

In Python terms, snapshot testing captures the output of your functions, API responses, or generated files and stores them as “snapshots”. These snapshots serve as the expected output for future test runs. This means you can:

• ✨ Detect unintended changes automatically
• 🚀 Test complex outputs without writing assertions
• 🛡️ Protect against regression bugs

💡 Why Use Snapshot Testing?

Here’s why developers love snapshot testing:

1. Effortless Testing 🔒: No need to write complex assertions
2. Visual Diffs 💻: See exactly what changed when tests fail
3. Regression Protection 📖: Catch unexpected changes instantly
4. Time Saver 🔧: Write tests in seconds, not minutes

Real-world example: Imagine building a report generator 📊. With snapshot testing, you can capture the entire report output and ensure it never changes unexpectedly when you refactor your code!

🔧 Basic Syntax and Usage

📝 Simple Example with pytest-snapshot

Let’s start with a friendly example using the popular pytest-snapshot library:

# 👋 Hello, Snapshot Testing!
import pytest

def generate_user_profile(name, age, hobbies):
    # 🎨 Creating a user profile
    profile = f"""
    ===== User Profile =====
    Name: {name}
    Age: {age}
    Hobbies: {', '.join(hobbies)}
    Status: Active
    =======================
    """
    return profile.strip()

def test_user_profile(snapshot):
    # 🚀 Generate a profile
    profile = generate_user_profile(
        "Alice", 
        28, 
        ["Python", "Reading", "Gaming"]
    )
    
    # 📸 Take a snapshot!
    snapshot.assert_match(profile)

💡 Explanation: The snapshot fixture automatically captures the output and compares it with stored snapshots. Magic! ✨

🎯 Common Patterns

Here are patterns you’ll use daily:

# 🏗️ Pattern 1: JSON snapshots
import json

def get_api_response():
    return {
        "status": "success",
        "data": {"users": 150, "active": 142},
        "timestamp": "2024-01-15"
    }

def test_api_response(snapshot):
    response = get_api_response()
    # 🎨 Pretty print JSON for readable snapshots
    snapshot.assert_match(json.dumps(response, indent=2))

# 🔄 Pattern 2: HTML snapshots
def generate_html_report(data):
    return f"""
    <div class="report">
        <h1>Sales Report 📊</h1>
        <p>Total: ${data['total']}</p>
        <p>Items: {data['items']}</p>
    </div>
    """

def test_html_report(snapshot):
    report = generate_html_report({"total": 1500, "items": 25})
    snapshot.assert_match(report)

# 🎯 Pattern 3: Custom snapshot names
def test_multiple_scenarios(snapshot):
    # 📸 Name your snapshots for clarity
    snapshot.assert_match(
        generate_user_profile("Bob", 30, ["Coding"]), 
        "bob_profile"
    )
    snapshot.assert_match(
        generate_user_profile("Carol", 25, ["Art", "Music"]), 
        "carol_profile"
    )

💡 Practical Examples

🛒 Example 1: E-commerce Order Receipt

Let’s build a real-world order receipt generator:

# 🛍️ Order receipt generator
from datetime import datetime
from typing import List, Dict

class OrderReceipt:
    def __init__(self, order_id: str):
        self.order_id = order_id
        self.items: List[Dict] = []
        self.date = datetime.now().strftime("%Y-%m-%d")
    
    # ➕ Add item to receipt
    def add_item(self, name: str, price: float, quantity: int, emoji: str = "📦"):
        self.items.append({
            "name": name,
            "price": price,
            "quantity": quantity,
            "emoji": emoji
        })
    
    # 💰 Calculate total
    def calculate_total(self) -> float:
        subtotal = sum(item["price"] * item["quantity"] for item in self.items)
        tax = subtotal * 0.08  # 8% tax
        return subtotal + tax
    
    # 📋 Generate receipt
    def generate(self) -> str:
        receipt = f"""
╔═══════════════════════════════════════╗
║         🛒 SUPER STORE RECEIPT        ║
╠═══════════════════════════════════════╣
║ Order ID: {self.order_id:<27} ║
║ Date: {self.date:<30} ║
╠═══════════════════════════════════════╣
"""
        
        # Add items
        for item in self.items:
            line = f"║ {item['emoji']} {item['name']:<20} x{item['quantity']:<3} ${item['price'] * item['quantity']:>7.2f} ║"
            receipt += line + "\n"
        
        # Add totals
        subtotal = sum(item["price"] * item["quantity"] for item in self.items)
        tax = subtotal * 0.08
        total = self.calculate_total()
        
        receipt += f"""╠═══════════════════════════════════════╣
║ Subtotal:                    ${subtotal:>8.2f} ║
║ Tax (8%):                    ${tax:>8.2f} ║
║ Total:                       ${total:>8.2f} ║
╚═══════════════════════════════════════╝
        
        Thank you for shopping! 🎉"""
        
        return receipt.strip()

# 🧪 Test with snapshots
def test_order_receipt(snapshot):
    # Create an order
    receipt = OrderReceipt("ORD-12345")
    receipt.add_item("Python Book", 29.99, 1, "📘")
    receipt.add_item("Coffee Mug", 12.99, 2, "☕")
    receipt.add_item("Laptop Sticker", 4.99, 5, "💻")
    
    # 📸 Snapshot the entire receipt!
    snapshot.assert_match(receipt.generate())

🎯 Try it yourself: Add a discount feature and update your snapshots!

🎮 Example 2: Game State Serializer

Let’s make a game save system:

# 🏆 Game state manager
import json
from typing import List, Dict, Any

class GameState:
    def __init__(self, player_name: str):
        self.player_name = player_name
        self.level = 1
        self.score = 0
        self.inventory: List[Dict[str, Any]] = []
        self.achievements: List[str] = ["🌟 Welcome Adventurer!"]
        self.position = {"x": 0, "y": 0, "zone": "Starting Village"}
    
    # 🎮 Game actions
    def add_score(self, points: int):
        self.score += points
        # 🎊 Level up every 100 points
        if self.score >= self.level * 100:
            self.level_up()
    
    def level_up(self):
        self.level += 1
        self.achievements.append(f"🏆 Reached Level {self.level}")
    
    def collect_item(self, item: str, emoji: str, value: int):
        self.inventory.append({
            "name": item,
            "emoji": emoji,
            "value": value,
            "collected_at_level": self.level
        })
        
        # 🎯 Special achievements
        if len(self.inventory) == 10:
            self.achievements.append("🎒 Collector - 10 items!")
    
    def move_to(self, x: int, y: int, zone: str):
        self.position = {"x": x, "y": y, "zone": zone}
    
    # 📸 Serialize for snapshot
    def serialize(self) -> str:
        state = {
            "player": {
                "name": self.player_name,
                "level": self.level,
                "score": self.score
            },
            "position": self.position,
            "inventory": sorted(self.inventory, key=lambda x: x["name"]),
            "achievements": self.achievements,
            "stats": {
                "total_items": len(self.inventory),
                "total_value": sum(item["value"] for item in self.inventory)
            }
        }
        
        # 🎨 Pretty format for readable snapshots
        return json.dumps(state, indent=2, sort_keys=True)

# 🧪 Test game state snapshots
def test_game_progression(snapshot):
    # 🎮 Simulate a game session
    game = GameState("Alice")
    
    # Play the game!
    game.add_score(50)
    game.collect_item("Magic Sword", "⚔️", 100)
    game.collect_item("Health Potion", "🧪", 25)
    game.move_to(10, 20, "Dark Forest")
    
    # Level up!
    game.add_score(60)  # Total: 110, triggers level up
    game.collect_item("Golden Crown", "👑", 500)
    
    # 📸 Snapshot the game state
    snapshot.assert_match(game.serialize(), "game_state_level_2")

🚀 Advanced Concepts

🧙‍♂️ Dynamic Snapshot Updates

When you’re ready to level up, try these advanced patterns:

# 🎯 Filtering dynamic data
import re
from datetime import datetime

def normalize_timestamps(text: str) -> str:
    # ✨ Replace timestamps with placeholder
    timestamp_pattern = r'\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}'
    return re.sub(timestamp_pattern, '<TIMESTAMP>', text)

def normalize_ids(text: str) -> str:
    # 🔧 Replace UUIDs with placeholder
    uuid_pattern = r'[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}'
    return re.sub(uuid_pattern, '<UUID>', text)

def test_dynamic_content(snapshot):
    # Generate content with dynamic values
    report = f"""
    Report Generated: {datetime.now()}
    Session ID: {generate_uuid()}
    Status: Completed
    """
    
    # 🪄 Normalize before snapshot
    normalized = normalize_timestamps(report)
    normalized = normalize_ids(normalized)
    
    snapshot.assert_match(normalized)

🏗️ Custom Snapshot Matchers

For the brave developers:

# 🚀 Custom snapshot serializer
class HTMLSnapshotSerializer:
    def __init__(self):
        self.prettify = True
    
    def serialize(self, html: str) -> str:
        if self.prettify:
            # 🎨 Format HTML nicely
            from bs4 import BeautifulSoup
            soup = BeautifulSoup(html, 'html.parser')
            return soup.prettify()
        return html
    
    def deserialize(self, data: str) -> str:
        return data

# Using custom serializer
def test_html_with_serializer(snapshot):
    html = "<div><h1>Title</h1><p>Content</p></div>"
    
    serializer = HTMLSnapshotSerializer()
    formatted = serializer.serialize(html)
    
    snapshot.assert_match(formatted)

⚠️ Common Pitfalls and Solutions

😱 Pitfall 1: Dynamic Data in Snapshots

# ❌ Wrong way - timestamps change every run!
def get_log_entry():
    return f"[{datetime.now()}] User logged in 😰"

def test_bad_snapshot(snapshot):
    snapshot.assert_match(get_log_entry())  # 💥 Fails every time!

# ✅ Correct way - normalize dynamic data!
def get_log_entry_normalized():
    return "[<TIMESTAMP>] User logged in 🛡️"

def test_good_snapshot(snapshot):
    entry = get_log_entry()
    normalized = re.sub(r'\[.*?\]', '[<TIMESTAMP>]', entry)
    snapshot.assert_match(normalized)  # ✅ Stable snapshot!

🤯 Pitfall 2: Large Snapshots

# ❌ Dangerous - huge snapshots are hard to review!
def test_entire_database_dump(snapshot):
    huge_data = fetch_entire_database()  # 💥 10MB snapshot!
    snapshot.assert_match(str(huge_data))

# ✅ Safe - snapshot only what matters!
def test_summary_data(snapshot):
    data = fetch_entire_database()
    summary = {
        "total_records": len(data),
        "categories": list(set(item["category"] for item in data)),
        "date_range": {
            "start": min(item["date"] for item in data),
            "end": max(item["date"] for item in data)
        }
    }
    snapshot.assert_match(json.dumps(summary, indent=2))  # ✅ Concise!

🛠️ Best Practices

1. 🎯 Normalize Dynamic Data: Remove timestamps, IDs, and random values
2. 📝 Review Snapshots: Always review snapshot changes before committing
3. 🛡️ Keep Snapshots Small: Large snapshots are hard to review and maintain
4. 🎨 Format for Readability: Use pretty-printing for JSON/HTML
5. ✨ Update Intentionally: Only update snapshots when changes are expected

🧪 Hands-On Exercise

🎯 Challenge: Build a Weather Report Snapshot System

Create a weather report generator with snapshot testing:

📋 Requirements:

• ✅ Generate weather reports with temperature, conditions, and emoji
• 🏷️ Support multiple cities and forecast types
• 👤 Include weather alerts and recommendations
• 📅 Handle 5-day forecasts
• 🎨 Each weather condition needs an emoji!

🚀 Bonus Points:

• Filter out dynamic timestamps
• Create formatted text and JSON outputs
• Add severe weather alerts

💡 Solution

# 🎯 Weather report system with snapshots!
import json
from typing import List, Dict, Optional
from datetime import datetime, timedelta

class WeatherReport:
    def __init__(self, city: str):
        self.city = city
        self.current_temp = 0
        self.condition = ""
        self.emoji = "☀️"
        self.forecast: List[Dict] = []
        self.alerts: List[str] = []
    
    # 🌡️ Set current weather
    def set_current(self, temp: int, condition: str):
        self.current_temp = temp
        self.condition = condition
        self.emoji = self._get_weather_emoji(condition)
        
        # 🚨 Auto-generate alerts
        if temp > 35:
            self.alerts.append("🔥 Extreme heat warning!")
        elif temp < 0:
            self.alerts.append("❄️ Freezing conditions!")
        if "storm" in condition.lower():
            self.alerts.append("⛈️ Storm warning - stay safe!")
    
    # 🎨 Weather emoji mapping
    def _get_weather_emoji(self, condition: str) -> str:
        emoji_map = {
            "sunny": "☀️",
            "cloudy": "☁️",
            "rainy": "🌧️",
            "stormy": "⛈️",
            "snowy": "❄️",
            "foggy": "🌫️",
            "windy": "💨"
        }
        return emoji_map.get(condition.lower(), "🌤️")
    
    # 📅 Add forecast day
    def add_forecast_day(self, day_offset: int, temp: int, condition: str):
        self.forecast.append({
            "day": f"Day +{day_offset}",
            "temp": temp,
            "condition": condition,
            "emoji": self._get_weather_emoji(condition)
        })
    
    # 📋 Generate text report
    def generate_text_report(self) -> str:
        report = f"""
╔═══════════════════════════════════════╗
║        🌍 WEATHER REPORT              ║
╠═══════════════════════════════════════╣
║ City: {self.city:<31} ║
║ Current: {self.emoji} {self.current_temp}°C {self.condition:<19} ║
╠═══════════════════════════════════════╣
║           📅 5-DAY FORECAST           ║
╠═══════════════════════════════════════╣
"""
        
        for day in self.forecast:
            line = f"║ {day['day']:<8} {day['emoji']} {day['temp']}°C {day['condition']:<17} ║"
            report += line + "\n"
        
        if self.alerts:
            report += "╠═══════════════════════════════════════╣\n"
            report += "║           ⚠️  ALERTS                  ║\n"
            report += "╠═══════════════════════════════════════╣\n"
            for alert in self.alerts:
                report += f"║ {alert:<37} ║\n"
        
        report += "╚═══════════════════════════════════════╝"
        return report.strip()
    
    # 📊 Generate JSON report
    def generate_json_report(self) -> str:
        data = {
            "city": self.city,
            "generated": "<TIMESTAMP>",  # Normalized!
            "current": {
                "temperature": self.current_temp,
                "condition": self.condition,
                "emoji": self.emoji
            },
            "forecast": self.forecast,
            "alerts": self.alerts,
            "recommendations": self._get_recommendations()
        }
        return json.dumps(data, indent=2)
    
    # 💡 Get recommendations
    def _get_recommendations(self) -> List[str]:
        recs = []
        if self.current_temp > 30:
            recs.append("💧 Stay hydrated!")
        if self.current_temp < 10:
            recs.append("🧥 Dress warmly!")
        if "rain" in self.condition.lower():
            recs.append("☂️ Don't forget your umbrella!")
        return recs

# 🧪 Test the weather reports
def test_weather_reports(snapshot):
    # Create a weather report
    weather = WeatherReport("San Francisco")
    weather.set_current(22, "Sunny")
    
    # Add 5-day forecast
    weather.add_forecast_day(1, 24, "Sunny")
    weather.add_forecast_day(2, 20, "Cloudy")
    weather.add_forecast_day(3, 18, "Rainy")
    weather.add_forecast_day(4, 19, "Cloudy")
    weather.add_forecast_day(5, 23, "Sunny")
    
    # 📸 Snapshot both formats
    snapshot.assert_match(weather.generate_text_report(), "sf_text_report")
    snapshot.assert_match(weather.generate_json_report(), "sf_json_report")
    
    # Test extreme weather
    extreme = WeatherReport("Phoenix")
    extreme.set_current(42, "Sunny")
    extreme.add_forecast_day(1, 44, "Sunny")
    
    snapshot.assert_match(extreme.generate_text_report(), "phoenix_extreme_heat")

🎓 Key Takeaways

You’ve learned so much! Here’s what you can now do:

• ✅ Create snapshot tests with confidence 💪
• ✅ Handle dynamic data in snapshots properly 🛡️
• ✅ Write maintainable tests for complex outputs 🎯
• ✅ Debug test failures with visual diffs 🐛
• ✅ Build robust test suites with snapshot testing! 🚀

Remember: Snapshot testing is your safety net for complex outputs. It catches changes you might miss! 🤝

🤝 Next Steps

Congratulations! 🎉 You’ve mastered snapshot testing!

Here’s what to do next:

1. 💻 Practice with the weather report exercise
2. 🏗️ Add snapshot tests to your existing projects
3. 📚 Explore advanced snapshot libraries like syrupy or snapshottest
4. 🌟 Share your snapshot testing success stories!

Remember: Every test you write makes your code more reliable. Keep testing, keep learning, and most importantly, have fun! 🚀

Happy testing! 🎉🚀✨