Skip to main content

Test Environment Setup

To set up a stable and predictable environment for running test suites in this project, you should use the TestingConfig class when initializing the application factory.

Initializing the Test Application​

Use the create_app factory from app/__init__.py and pass TestingConfig as the config_class argument. This ensures the application is configured with testing-specific overrides.

from app import create_app
from app.config import TestingConfig

def test_setup():
    # Initialize the app with TestingConfig
    app = create_app(config_class=TestingConfig)
    
    # Verify the environment
    assert app.config['TESTING'] is True
    assert app.config['PAGE_SIZE'] == 5
    
    return app.test_client()

Testing Configuration Properties​

The TestingConfig class (found in app/config.py) inherits from BaseConfig and provides two critical overrides for the test environment:

  • TESTING: Set to True. This enables Flask's testing mode, which allows for better error reporting and behavior during test execution.
  • PAGE_SIZE: Reduced to 5 (from the default 25). This is specifically designed to make testing pagination logic easier by requiring fewer items to trigger multiple pages.
@dataclass
class TestingConfig(BaseConfig):
    """Configuration for test runs."""

    TESTING: bool = True
    PAGE_SIZE: int = 5

Managing State Between Tests​

Because this application uses an in-memory repository, state persists for the lifetime of the BookmarkService singleton. To ensure test isolation, you must manually reset the service state between test cases using the internal _reset() method.

Resetting the Service Layer​

The BookmarkService provides a _reset() method that re-initializes the repository, cache, and search index.

from app.services.bookmark_service import BookmarkService

def setup_function():
    """Reset the singleton state before each test."""
    service = BookmarkService()
    service._reset()

Clearing the Repository Directly​

If you need to wipe the data without re-initializing the entire service stack, you can call _clear_all() on the BookmarkRepository instance.

from app.db.repository import BookmarkRepository

repo = BookmarkRepository()
repo._clear_all()  # Wipes bookmarks, tags, and collections

Troubleshooting and Gotchas​

Pagination Mismatch​

The most common issue when using TestingConfig is a mismatch in expected item counts. If your tests were written against the DevelopmentConfig (where PAGE_SIZE is 10) or ProductionConfig (where PAGE_SIZE is 25), they may fail when running under TestingConfig because pagination will trigger after only 5 items.

Singleton Persistence​

Since BookmarkService is a singleton (implemented via __new__ in app/services/bookmark_service.py), simply creating a new Flask app instance does not reset the underlying data. You must explicitly call BookmarkService()._reset() in your test setup or teardown to prevent state leakage between tests.

# app/services/bookmark_service.py

def _reset(self) -> None:
    """Tear down and reinitialise — used in tests only."""
    self._init_services()