Energy Burden Analysis Using Net Energy Return Methodology.

Testing Framework for emburden Package

This directory contains comprehensive tests for the emburden package, including unit tests, integration tests, and a local test runner.

Running Tests

Quick Local Test Run

From the package root directory:

Rscript tests/run-tests-locally.R

Or from R console:

source("tests/run-tests-locally.R")

Full R CMD Check

To run complete package checks (like GitHub Actions):

RUN_CMD_CHECK=true Rscript tests/run-tests-locally.R

Run Specific Test Files

From R console:

devtools::load_all()
testthat::test_file("tests/testthat/test-energy-metrics.R")

Coverage Report

covr::package_coverage()
covr::report()  # Opens HTML report in browser

Test Organization

Phase 1: Critical Tests (Implemented)

• test-file-validation.R: Data quality checks, edge cases, fixture generation
• test-energy-metrics.R: Core NER, energy burden, and related calculations

Phase 2: High Priority (Planned)

• test-data-loaders.R: HTTP mocking, database tests, file loading
• test-schema-normalization.R: Vintage compatibility, bracket aggregation

Phase 3: Medium Priority (Planned)

• test-integration.R: End-to-end workflows
• test-formatting.R: Output formatting functions

Helper Files

• helper-fixtures.R: Test data generation and cleanup utilities
  • create_sample_lead_data(): Generate realistic test data
  • create_corrupted_fpl_data(): Test all-NA income_bracket bug
  • create_test_database(): SQLite database for testing
  • cleanup_test_files(): Remove temporary files

Writing New Tests

Template for New Test File

# Phase X: Description
# Tests for specific functionality

test_that("descriptive test name", {
  # Arrange: Set up test data
  data <- create_sample_lead_data(n = 50)

  # Act: Perform the operation
  result <- some_function(data)

  # Assert: Check expectations
  expect_equal(result$value, expected_value)
  expect_true(some_condition)
})

Best Practices

1. Use fixtures: Don't rely on external data - use create_sample_lead_data()
2. Test edge cases: Zero, negative, NA, Inf values
3. Clean up: Use cleanup_test_files() to remove temporary files
4. Skip when appropriate: Use skip_if_offline() for network tests
5. Descriptive names: Test names should describe what's being tested

Coverage Goals

Continuous Integration

Tests run automatically on:

• Pull requests targeting main branch
• Pushes to main branch
• Multiple OS/R version combinations (macOS, Windows, Ubuntu)

See .github/workflows/R-CMD-check.yml and .github/workflows/test-coverage.yml for details.

Debugging Failed Tests

View Detailed Output

devtools::test(reporter = "check")  # More verbose than default

Interactive Debugging

devtools::load_all()
library(testthat)

# Set breakpoint in your test
test_that("my failing test", {
  browser()  # Execution will pause here
  # ... test code ...
})

Check Test Data

# Generate and inspect test data
data <- create_sample_lead_data(n = 10)
str(data)
summary(data)

Test Data Fixtures

Test fixtures are generated on-the-fly using helper-fixtures.R. This ensures:

1. No large data files in git: Fixtures are created during test runs
2. Reproducibility: Seed values ensure consistent test data
3. Flexibility: Easy to modify fixture characteristics
4. Speed: Minimal data creation for fast tests

Example Fixture Usage

# Create standard test data
data <- create_sample_lead_data(n = 100, dataset = "ami", vintage = "2022")

# Create edge case data
edge_data <- create_edge_case_data()

# Create corrupted data (for testing validation)
corrupted <- create_corrupted_fpl_data(n = 50)

Performance Benchmarks

Target test suite execution time:

• Unit tests: < 30 seconds
• Integration tests: < 60 seconds
• Full suite with coverage: < 2 minutes

Adding Tests for New Features

When adding new features:

1. Write tests first (TDD approach preferred)
2. Ensure new code has >85% coverage
3. Add integration tests for major features
4. Update this README with new test files

Troubleshooting

"Package not installed" Error

# Install in development mode
Rscript -e "devtools::install()"

Missing Test Dependencies

# Install testing packages
install.packages(c("testthat", "covr", "withr", "mockery"))

Tests Pass Locally but Fail in CI

• Check R version differences
• Verify all dependencies in DESCRIPTION
• Check for hardcoded paths
• Ensure fixtures are platform-independent

Additional Resources

• testthat documentation
• covr package
• R Packages book - Testing chapter
• Testing spec document.