Developer Documentation

Testing

FOAMFlask includes a comprehensive test suite using pytest. The test suite includes unit tests, integration tests, and end-to-end tests for the application's core functionality.

Running Tests

1. Install test dependencies (if not already installed):

   uv sync

2. Run all tests with coverage:

   # Run all tests with coverage
   uv run pytest --cov=app --cov=backend --cov-report=term-missing --cov-report=html

3. Run specific test files or individual tests:

   # Run a specific test file
   uv run pytest test/test_app.py -v
   
   # Run a specific test function
   uv run pytest test/test_app.py::test_index_route -v

4. Run tests in parallel (faster execution):

   uv run pytest -n auto --cov=app --cov=backend

Test Coverage

To check test coverage and generate reports:

# Generate HTML coverage report (recommended)
uv run pytest --cov=app --cov=backend --cov-report=html

# View coverage in terminal
uv run pytest --cov=app --cov=backend --cov-report=term-missing

# Generate XML report (for CI/CD integration)
uv run pytest --cov=app --cov=backend --cov-report=xml

Coverage Reports:

• HTML report will be generated in the htmlcov directory
• Open htmlcov/index.html in your browser to view the detailed coverage report
• The terminal report shows which lines are missing coverage

Test Structure

test/
├── conftest.py        # Test fixtures and configuration
├── test_app.py        # Main application tests
└── test_security.py   # Security-related tests

Writing New Tests

1. Create a new test file following the naming convention test_*.py
2. Use pytest fixtures from conftest.py when available
3. Follow the existing test patterns for consistency
4. Include docstrings explaining what each test verifies

Test Coverage Commands Reference

# Run all tests with coverage
uv run pytest --cov=app --cov=backend

# Run tests without coverage
uv run pytest

# Run tests with detailed output
uv run pytest -v

# Run tests and stop after first failure
uv run pytest -x

# Run tests and show output from print statements
uv run pytest -s

# Run tests matching a specific pattern
uv run pytest -k "test_name_pattern"

---

For users who want to contribute or fork the project.

Project Architecture: Explain the folder structure (Flask backend, static/ HTML/JS frontend).

API Endpoints: A brief overview of the Flask routes that serve the plot data and execute commands.

Generating Docs: The pdoc commands currently at the bottom of your wiki for generating Python HTML/Markdown documentation.

Building/Extending: How to add new OpenFOAM command buttons or new plot types.