forensic-trails/tests/README.md

ForensicTrails Test Suite

Overview

This directory contains unit and integration tests for the ForensicTrails application.

Running Tests

Run all tests

python -m pytest tests/

Run specific test file

python -m pytest tests/test_database.py

Run with verbose output

python -m pytest tests/test_database.py -v

Run with coverage report

python -m pytest tests/test_database.py --cov=forensictrails.db.database --cov-report=term-missing

Run specific test class or method

python -m pytest tests/test_database.py::TestGetDbConnection
python -m pytest tests/test_database.py::TestGetDbConnection::test_get_db_connection_creates_file

Test Files

test_database.py

Comprehensive tests for the database module (forensictrails.db.database).

Coverage: 94%

Test Classes

• TestGetDbConnection: Tests for get_db_connection() function

  • Connection creation and file creation

• TestValidateDatabaseSchema: Tests for validate_database_schema() function

  • Empty database validation
  • Incomplete database validation
  • Complete database validation
  • Non-existent database validation

• TestCreateFreshDatabase: Tests for create_fresh_database() function

  • Database file creation
  • All required tables creation
  • Return value verification
  • Clean path behavior

• TestInitializeDatabase: Tests for initialize_database() function

  • New database creation
  • Valid database preservation
  • Invalid database recreation

• TestShowDbSchema: Tests for show_db_schema() function

  • Logging behavior
  • Exception handling

• TestDatabaseIntegration: Full lifecycle integration tests

  • Complete workflow: create → use → corrupt → recreate
  • Data persistence and loss scenarios

Test Coverage Summary

Module	Statements	Missing	Coverage
forensictrails.db.database	65	4	94%

Uncovered Lines

• Line 10: Config fallback in get_db_connection() (uses mocked config in tests)
• Line 48: Config fallback in create_fresh_database() (uses explicit paths in tests)
• Line 69: Config fallback in initialize_database() (uses explicit paths in tests)
• Line 91: Debug logging in show_db_schema() (covered but not counted due to mocking)

These uncovered lines are primarily default parameter handling that relies on the global config object, which is mocked in tests.

Test Design Principles

1. Isolation: Each test uses temporary directories and cleans up after itself
2. Independence: Tests don't depend on each other and can run in any order
3. Mocking: External dependencies (config, logging) are mocked where appropriate
4. Real Database: Tests use actual SQLite databases to ensure realistic behavior
5. Comprehensive: Tests cover success paths, error paths, and edge cases

Adding New Tests

When adding new database functionality:

1. Add unit tests for individual functions
2. Add integration tests for complex workflows
3. Ensure cleanup in tearDown() methods
4. Use descriptive test names that explain what is being tested
5. Run coverage to ensure new code is tested

Dependencies

Tests require:

• pytest - Test framework
• pytest-cov - Coverage reporting
• Standard library: unittest, tempfile, sqlite3

Install test dependencies:

pip install pytest pytest-cov