accounting-conservation-framework

Pedagogy Test Suite - Testing Guide

Overview

The pedagogy test suite (tests/pedagogy/) bridges the gap between Derek Stone’s intuitive YouTube explanation of Pacioli’s double-entry bookkeeping and the formal mathematical framework in this repository.

Purpose: Make the framework’s rigor accessible to students and practitioners by showing how classical accounting concepts map to graph theory, conservation laws, and the discrete Reynolds Transport Theorem.

Quick Start

# Run all pedagogy tests
pytest tests/pedagogy/ -v

# Run with verbose output (shows ASCII diagrams)
pytest tests/pedagogy/ -v -s

# Run property-based tests thoroughly (300 examples each)
HYPOTHESIS_PROFILE=thorough pytest tests/pedagogy/property_based/ -v

# Run a specific test file
pytest tests/pedagogy/test_pacioli_worksheet.py -v -s

Test Organization

tests/pedagogy/
├── conftest.py                          # Shared fixtures (Ledger, JournalEntry, etc.)
├── test_pacioli_worksheet.py            # Derek Stone's "Robbie" examples
├── test_kirchhoff_pedagogy.py           # Why balance sheets balance
└── property_based/
    ├── conftest.py                       # Hypothesis configuration
    └── test_pacioli_invariants.py        # Universal properties (Hypothesis)

Test Files

1. `test_pacioli_worksheet.py` - Derek Stone’s Robbie Examples

Purpose: Demonstrate all three frameworks using Derek’s narrative.

What it tests:

Complete “Robbie” business scenario (owner investment through profit calculation)
Cash vs. accrual accounting (A/R and A/P)
Advanced scenario with OCI, dividends, and NCI

Three views of same transactions:

Worksheet/Ledger View (Derek’s pedagogy):
- Visual ASCII tables
- Debits and credits
- Self-balancing rows
Incidence Matrix View (Ellerman 1982):
- Rows = accounts, columns = entries
- Kirchhoff’s law: 1ᵀ·B = 0
- Proof that A = L + E follows algebraically
Equity Bridge View (This framework):
- ΔE_parent = (NI + OCI) + Owner + Meas - ΔNCI
- Discrete RTT formula
- Extends beyond Pacioli’s 15th-century limits

Example output:

╔═══════════════════════════════════════════════════════════╗
║              ROBBIE'S WORKSHEET (Period 1)                ║
╠═══════════════════════════════════════════════════════════╣
║  Assets & Expenses     │     Liabilities, Equity, Revenue ║
║  Cash            775   │     Capital           -1,000     ║
║  Inventory       250   │     Revenue             -225     ║
║  COGS Expense    150   │                                  ║
║  Wages Expense    50   │                                  ║
╠════════════════════════╧══════════════════════════════════╣
║  Net: 1,225 + (-1,225) = 0  ✓ BALANCED                    ║
╚═══════════════════════════════════════════════════════════╝

Derek Stone video timestamps referenced in tests:

0:01-2:22: Pacioli paradox (rules without proof)
4:06-8:08: Worksheet concept (assets = liabilities)
9:09-11:18: “Subtract RHS” → self-balancing rows
16:04-17:50: Debits/credits = disguised +/−
19:50-22:08: Extract P&L, cash flow, balance sheet

2. `test_kirchhoff_pedagogy.py` - Balance Sheet Conservation

Purpose: Answer the #1 student question: “Does A=L+E break if I’m gifted a building?”

What it tests:

Gifted building (shareholder contribution → equity)
Gifted building (government grant → liability, IAS 20)
Incidence matrix verification (Kirchhoff’s law)
All source terms preserve conservation
Derek’s proof: debits = credits ⟺ self-balancing ⟺ 1ᵀ·B=0

Key theorem proved:

Theorem 1 (Kirchhoff’s Accounting Theorem):

If every journal entry satisfies Axiom 1 (Σ postings = 0), then Σ all balances = 0, which is equivalent to A = L + E.

Student FAQ coverage:

“Where does equity come from if gifted an asset?” → Source term (balanced entry)
“Is equity just a plug?” → No, it’s a conservation residual
“Why do debits always equal credits?” → Kirchhoff’s law

3. `property_based/test_pacioli_invariants.py` - Universal Properties

Purpose: Use Hypothesis to prove laws hold for ALL possible transactions.

What it tests:

Property 1: Every generated entry satisfies Axiom 1 (Σ = 0)
Property 2: Any sequence of entries preserves A = L + E
Property 3: Transaction order doesn’t matter (commutativity)
Property 4: Debits have “hot/cold air” effect (Derek’s insight)
Property 5: Source terms always have balanced entries

Hypothesis strategies:

balanced_entry_strategy(): Generate valid journal entries
entry_sequence_strategy(): Generate 1-10 random entries
posting_strategy(): Generate (account, amount) pairs

Run profiles:

# Quick check (25 examples)
HYPOTHESIS_PROFILE=dev pytest tests/pedagogy/property_based/ -v

# CI/CD (75 examples)
HYPOTHESIS_PROFILE=ci pytest tests/pedagogy/property_based/ -v

# Thorough (300 examples)
HYPOTHESIS_PROFILE=thorough pytest tests/pedagogy/property_based/ -v

Pedagogical value:

Shows students that laws are mathematical theorems, not arbitrary rules
Demonstrates universality (no exceptions for “gifts”, etc.)
Builds confidence that A=L+E holds ALWAYS

Video Timestamp → Test Mapping

Derek Stone Video Timestamp	Concept	Test Location
0:01-2:22	Pacioli: rules without proof	docs/pedagogy/MATHEMATICAL_FOUNDATIONS_HISTORY.md
4:06-5:38	Separate entity (owner is liability)	test_pacioli_worksheet.py::test_robbie_t1_owner_invests_cash
5:38-6:03	Buy inventory (asset-to-asset)	test_pacioli_worksheet.py::test_robbie_t2_buy_inventory_cash
6:03-8:08	First sale (revenue, COGS, matching)	test_pacioli_worksheet.py::test_robbie_t3_cash_sale_with_cogs
8:16-9:09	Credit sales (A/R, A/P)	test_pacioli_worksheet.py::test_robbie_credit_sales_scenario
9:09-11:18	“Subtract RHS” → self-balancing	test_kirchhoff_pedagogy.py::test_kirchhoff_law_incidence_matrix
13:05-14:20	Two columns (debits/credits)	test_kirchhoff_pedagogy.py::test_derek_stone_debits_equal_credits_proof
16:04-17:50	Debits/credits = disguised +/−	conftest.py::Posting (documented in docstring)
18:22-19:42	“Hot/cold air” (debit effect varies)	property_based/test_pacioli_invariants.py::test_property_debit_effect_depends_on_account_type
19:50-22:08	Extract P&L, cash flow, balance sheet	test_pacioli_worksheet.py::test_robbie_complete_cash_scenario_three_views

Mapping to Framework Theorems

Derek’s Concepts → Formal Proofs

Derek’s Concept	Framework Theorem	Proof Location
“Self-balancing rows”	Axiom 1: Σ P_{i,j} = 0	docs/proofs/EQUITY_BRIDGE_PROOF.md
“Worksheet without equals sign”	1ᵀ·B = 0 (Kirchhoff)	docs/proofs/KIRCHHOFF_ACCOUNTING_THEOREM.md
“Assets = Liabilities + Equity”	Theorem 1 (follows from Axiom 1)	docs/proofs/KIRCHHOFF_ACCOUNTING_THEOREM.md
“Profit & loss from worksheet”	ΔE_parent = (NI + OCI) + …	docs/proofs/EQUITY_BRIDGE_PROOF.md
“Multi-year planning”	Discrete RTT recurrence	docs/proofs/DISCRETE_RTT_THEOREM.md

Shared Fixtures (conftest.py)

Core Classes

Posting(account, amount):

Single debit (+) or credit (−) posting
Properties: is_debit, is_credit
Derek’s insight: “Debits and credits are just disguised + and −”

JournalEntry(description, postings):

Collection of postings forming one transaction
Property: is_balanced (checks Axiom 1)
Methods: total_debits, total_credits

Ledger():

Simple T-account ledger for pedagogy
Methods: post(), balance(), trial_balance_sum()
Property: is_balanced() (checks A = L + E)

Fixtures

robbie_chart_of_accounts:

Derek Stone’s accounts (Cash, Inventory, Capital, Revenue, COGS, Wages)
Pre-configured normal sides (debit vs. credit)

pacioli_worksheet:

Converts ledger to worksheet dictionary
Shows Derek’s “subtract RHS” transformation

incidence_matrix_builder:

Converts journal entries to Ellerman’s matrix B
Returns (accounts, matrix) for Kirchhoff verification

ascii_worksheet_formatter:

Pretty-prints worksheet as ASCII table
Pedagogical visualization

Running Specific Scenarios

Robbie’s Complete Journey (Cash Basis)

pytest tests/pedagogy/test_pacioli_worksheet.py::test_robbie_complete_cash_scenario_three_views -v -s

Shows:

All transactions (T1-T4)
Final P&L, balance sheet
Incidence matrix verification
Equity bridge closure

Gifted Building Example

pytest tests/pedagogy/test_kirchhoff_pedagogy.py::test_gifted_building_shareholder_contribution -v -s

Shows:

Dr Building $1M / Cr Capital $1M
A = L + E still holds ($1M = $0 + $1M)
No magic, just balanced entry

Property-Based: 300 Random Tests

HYPOTHESIS_PROFILE=thorough pytest tests/pedagogy/property_based/ -v -s

Shows:

Hypothesis generates 300 random transaction sequences
All properties hold (no counterexamples found)
Strong evidence of universality

Pedagogical Flow

For Students New to Accounting

Start here: test_pacioli_worksheet.py::test_robbie_t1_owner_invests_cash
- Simplest case: owner invests cash
- See all three views (worksheet, matrix, bridge)
Build complexity: test_robbie_t2_buy_inventory_cash
- Asset-to-asset exchange
- Equity unchanged
First profit: test_robbie_t3_cash_sale_with_cogs
- Revenue, COGS, matching principle
- Calculate net income
Complete cycle: test_robbie_complete_cash_scenario_three_views
- All transactions together
- Extract financial statements
Accrual accounting: test_robbie_credit_sales_scenario
- A/R and A/P
- Timing differences

For Students Asking “Why?”

Why does A=L+E hold?
- test_kirchhoff_pedagogy.py::test_kirchhoff_law_incidence_matrix
- Proof via Kirchhoff’s law
What about gifts?
- test_kirchhoff_pedagogy.py::test_gifted_building_shareholder_contribution
- Shows source term is balanced
Are there any exceptions?
- property_based/test_pacioli_invariants.py
- Hypothesis finds NO counterexamples

For Framework Contributors

Understand the pedagogy layer:
- Read docs/pedagogy/MATHEMATICAL_FOUNDATIONS_HISTORY.md
- See Pacioli → Ellerman → 2025 timeline
Map new features to pedagogy:
- Add test showing intuitive explanation
- Add test showing formal proof
- Add property-based test for universality
Maintain ASCII visualizations:
- Keep ascii_worksheet_formatter up to date
- Add new formatters for new concepts (e.g., consolidation diagrams)

Extending the Test Suite

Adding a New Derek Stone Example

Extract timestamp and concept from video
Add test to test_pacioli_worksheet.py
Show all three views (worksheet, matrix, bridge)
Add ASCII visualization
Update this guide’s timestamp table

Adding a New Student Question

Document question in test_kirchhoff_pedagogy.py docstring
Create test showing why A=L+E still holds
Add balanced journal entry
Verify conservation
Add ASCII explanation

Adding a New Property

Add strategy to property_based/test_pacioli_invariants.py
Write @given test with clear docstring
Explain pedagogical value
Run with thorough profile to verify

Common Test Patterns

Pattern 1: Three-View Test

def test_my_scenario(...):
    # (a) Worksheet view
    entry = JournalEntry(...)
    for posting in entry.postings:
        ledger.post(posting.account, posting.amount)

    worksheet = pacioli_worksheet(ledger)
    print(ascii_worksheet_formatter(worksheet, "My Scenario"))

    # (b) Incidence matrix view
    accounts, matrix = incidence_matrix_builder([entry])
    assert all(sum(row[j]) == 0 for j in range(len(entries)))  # Kirchhoff

    # (c) Equity bridge view
    result = compute_equity_bridge(EquityBridgeInputs(...))
    assert result.passed

Pattern 2: Conservation Verification

def test_my_conservation_claim():
    ledger = Ledger()

    # ... post transactions ...

    # Verify A = L + E
    assert ledger.is_balanced()

    # Or compute explicitly
    assets = ...
    liabilities = ...
    equity = ...
    assert abs(assets - (liabilities + equity)) < 1e-9

Pattern 3: Property-Based Test

@given(my_strategy=...)
def test_property_my_invariant(my_strategy):
    """Property: [Universal claim]"""
    # ... perform operations ...
    assert [invariant holds]

Troubleshooting

Tests Fail with “conftest.py not found”

Cause: Python path not set correctly.

Fix: The conftest.py in tests/pedagogy/ sets up the path. Run from repo root:

cd /path/to/accounting-conservation-framework
pytest tests/pedagogy/ -v

Floating-Point Comparison Failures

Cause: Balances don’t sum to exactly zero due to floating-point arithmetic.

Fix: Always use tolerance in assertions:

assert abs(value - expected) < 1e-9  # NOT: assert value == expected

Hypothesis Flakiness

Cause: Hypothesis found a failing example but can’t reproduce.

Fix: Hypothesis saves examples in .hypothesis/ database. Run again to replay.

Contact & Contributions

Author: Nirvan Chitnis (with Claude Code assistance) Date: 2025-11-20

To contribute new pedagogy tests:

Fork the repo
Add tests following patterns above
Ensure all tests pass with pytest tests/pedagogy/ -v
Run property-based tests with HYPOTHESIS_PROFILE=thorough
Update this guide with new test documentation
Submit PR with clear explanation of pedagogical value

Goal: Make rigorous accounting theory accessible to students worldwide.

This site is open source. Improve this page.

accounting-conservation-framework

Pedagogy Test Suite - Testing Guide

Overview

Quick Start

Test Organization

Test Files

1. test_pacioli_worksheet.py - Derek Stone’s Robbie Examples

2. test_kirchhoff_pedagogy.py - Balance Sheet Conservation

3. property_based/test_pacioli_invariants.py - Universal Properties

Video Timestamp → Test Mapping

Mapping to Framework Theorems

Derek’s Concepts → Formal Proofs

Shared Fixtures (conftest.py)

Core Classes

Fixtures

Running Specific Scenarios

Robbie’s Complete Journey (Cash Basis)

Gifted Building Example

Property-Based: 300 Random Tests

Pedagogical Flow

For Students New to Accounting

For Students Asking “Why?”

For Framework Contributors

Extending the Test Suite

Adding a New Derek Stone Example

Adding a New Student Question

Adding a New Property

Common Test Patterns

Pattern 1: Three-View Test

Pattern 2: Conservation Verification

Pattern 3: Property-Based Test

Troubleshooting

Tests Fail with “conftest.py not found”

Floating-Point Comparison Failures

Hypothesis Flakiness

Further Reading

Historical Context

Formal Proofs

Derek Stone’s Video

Student Resources

Contact & Contributions

1. `test_pacioli_worksheet.py` - Derek Stone’s Robbie Examples

2. `test_kirchhoff_pedagogy.py` - Balance Sheet Conservation

3. `property_based/test_pacioli_invariants.py` - Universal Properties