Summary

This PR adds comprehensive documentation on how to configure FFI (Foreign Function Interface) logging in Pact Python. While the Python code uses the standard library logging module, the underlying Rust FFI cannot interface with it directly, requiring separate configuration.

Changes

New Documentation Page

Created docs/logging.md covering:

• Basic Configuration: How to use pact_ffi.log_to_stderr() to direct FFI logs to standard error
• Log Levels: Documentation of all available levels (OFF, ERROR, WARN, INFO, DEBUG, TRACE)
• Recommended Setup: Session-scoped pytest fixture example for conftest.py
• One-time Initialization: Clear warning that FFI logging can only be configured once per process
• Advanced Configuration: Coverage of log_to_buffer() for capturing logs to internal memory, with notes about features planned but not yet implemented
• Troubleshooting: Common issues and solutions
• API References: Links to complete API documentation

Updates to Existing Documentation

Added brief logging sections to both docs/consumer.md and docs/provider.md:

• Consumer Documentation: Added logging section after "Multi-Interaction Testing" explaining how to enable FFI logging for debugging mock service issues, with pytest fixture example and link to full documentation
• Provider Documentation: Added logging section after "Verifying from a Pact Broker" explaining how to enable FFI logging for debugging provider verification and state handlers, with pytest fixture example and link to full documentation

Example

The recommended setup for pytest users:

import pytest
import pact_ffi

@pytest.fixture(autouse=True, scope="session")
def pact_logging():
    """Configure Pact FFI logging for the test session."""
    pact_ffi.log_to_stderr("INFO")

Navigation Update

Updated docs/SUMMARY.md to include the new Logging page in the documentation menu.

Motivation

Users often struggle to understand why Pact FFI logs don't appear when using Python's standard logging configuration. This documentation addresses that confusion by:

1. Explaining the architectural reason (FFI can't interface with Python logging)
2. Providing clear, working examples
3. Warning about the one-time initialization constraint
4. Offering troubleshooting guidance
5. Making logging configuration discoverable from both consumer and provider documentation pages

Fixes #1302

Fixes #1302

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.