Netencode Integration Tests

This directory contains comprehensive integration tests for the netencode toolkit.

Test Structure

The test suite is written in Python using pytest and split into offline and network tests:

Note: The Python netencode module is now located at lib-python/netencode.py and uses standardized API function names.

Running Tests

Automated Testing (Recommended)

# Run all offline tests automatically (no network required)
# Runs 110 tests: 36 integration + 15 readme + 37 manpage + 22 python (offline)
nix-build -A netencode-tests

# Run specific test file
nix-build -A netencode-tests --arg testFiles '"test_integration.py"'
nix-build -A netencode-tests --arg testFiles '"test_manpage_examples.py"'

# Run tests matching a pattern
nix-build -A netencode-tests --arg pytestArgs '"-k json"'
nix-build -A netencode-tests --arg pytestArgs '"-k manpage"'

# Run with verbose output
nix-build -A netencode-tests --arg pytestArgs '"-v"'

Development Testing (Adhoc Testing Recommended)

For development and debugging, use nix-build with custom test scripts:

# Create a custom test script for debugging
cat > /tmp/debug-test.sh << 'EOF'
#!/bin/bash
echo "Debugging specific functionality..."
echo '{"test": "data"}' | json-to-netencode | netencode-pretty
echo "Testing record extraction..."
echo '{29:<4:name|t5:Alice,<3:age|i:30,}' | netencode-record-get name
EOF

# Run with nix-build (recommended for all development work)
nix-build -A netencode-tests --arg customTest /tmp/debug-test.sh --no-out-link

# Clean up
rm /tmp/debug-test.sh

Manual Testing (Network Tests Only)

Note: Only use nix-shell for network tests that cannot run in nix-build sandbox

# Enter test environment for network tests only
nix-shell tests/shell.nix

# Run network tests (requires internet)
pytest test_network.py -v

# Run all tests including network tests (requires internet)
pytest -v

Test Categories

Integration Tests (test_integration.py) - 36 tests

  1. JSON to Netencode Conversion

    • Simple objects, arrays, booleans, numbers, null values
    • Error handling for malformed JSON

  2. Netencode Filtering

    • Filter by text, number, and boolean fields
    • Handle missing fields gracefully
    • Pass through non-record values

  3. Pipeline Integration

    • Complete JSON → netencode → filter → extract workflows
    • Multi-record processing
    • Field ordering preservation

  4. Tool Compatibility

    • Cross-tool data format compatibility
    • Python-generated records work with CLI tools

  5. Netencode Plain Tool

    • Extract scalar values as plain text
    • Handle different data types correctly

  6. Edge Cases

    • Empty input handling
    • Unicode support
    • Special characters in field names and values
    • Environment integration

README Examples (test_readme_examples.py) - 15 tests (offline)

Tests for every example mentioned in the README to ensure documentation accuracy:

Man Page Examples (test_manpage_examples.py) - 37 tests (offline)

Tests for every example mentioned in the man pages to ensure documentation accuracy:

Format Specification (netencode.5):

Tool-Specific Examples:

Key Features Tested:

Python Module Tests (test_netencode_py.py) - 22 tests

Unit tests for the Python netencode construction module using the standardized API:

Network Tests (test_network.py) - 2 tests

Tests requiring internet connectivity (separated for nix-build):

Pretty Printer Tests (test_pretty_printer.py) - Comprehensive formatting validation

Standalone comprehensive tests for the netencode pretty-printer (not integrated into nix build):

Scalar Type Formatting:

Text Processing:

Binary Data Handling:

Complex Structure Formatting:

Output Format Verification:

Test Infrastructure

Nix-Build Testing

The preferred testing approach uses nix-build -A netencode-tests:

Manual Testing

The tests/shell.nix provides a lightweight development environment:

Test Features

Python Advantages

  1. No Shell Escaping Issues: Direct string handling without shell interpretation
  2. Clear Error Messages: Detailed assertion failures with context
  3. Easy Debugging: Simple to add print statements and inspect values
  4. Reliable Subprocess Handling: Python's subprocess module handles stdin/stdout correctly
  5. Organized Structure: Logical grouping into test classes with shared utilities

Tool Discovery

Tests work in both environments:

Contributing

When adding new functionality:

  1. Integration tests → test_integration.py (for tool behavior)
  2. README examples → test_readme_examples.py (for documentation accuracy)
  3. Man page examples → test_manpage_examples.py (for documentation validation)
  4. Python utilities → test_netencode_py.py (for netencode construction)
  5. Network tests → test_network.py (if requires internet)
  6. Cross-language tests → Reference GENERATOR_TEST_SPEC.md for consistent implementation across languages
  7. Use the run_tool() helper function for consistent tool execution
  8. Follow existing test structure and naming conventions
  9. Test with nix-build -A netencode-tests before submitting

Generator Test Specification

The GENERATOR_TEST_SPEC.md file defines a comprehensive test suite that all netencode language implementations (Haskell, Rust, Python, Nix) must pass. It includes:

This specification ensures that all language implementations produce identical netencode output for the same logical data, maintaining cross-language compatibility.