Unmasking the Singleton Anti-Pattern

This article was originally published on The New Stack.

The singleton pattern, a design pattern that restricts a class to a single instance, is often touted as a solution for managing shared resources or global state. While seemingly convenient, the singleton pattern often introduces subtle complexities and drawbacks that can undermine code maintainability and testability. This article delves into these issues, illustrating how dependency injection (DI) offers a more robust and flexible alternative.

The Singleton’s Deceptive Allure: A Testing Quagmire

Consider a common scenario: You’re developing an authentication module with unit tests ensuring its correctness. Your “happy path” test, which verifies successful authentication, passes without a hitch:

def test_user_authorized():
  with clean_db() as connection:
    app.create_user("bob", "secret")
    assert app.is_authorized("bob", "secret")

However, the subsequent test, designed to assert failed authorization, unexpectedly fails:

def test_user_unauthorized():
  with clean_db() as connection:
    assert not app.is_authorized("bob", "secret")

Upon investigation, you discover that someone named Jerry introduced a cache to enhance login performance. This cache, residing in the global scope as a simple dictionary, retains state across tests, thus polluting subsequent test runs and causing false negatives.

Your initial attempt to mitigate this issue involves resetting the global cache before each test:

def test_user_authorized():
  global cache
  cache = dict()  # Reset the global cache
  # ... rest of the test

def test_user_unauthorized():
  global cache
  cache = dict()  # Reset the global cache
  # ... rest of the test

While this workaround temporarily restores test integrity, it’s a fragile solution, highlighting the perils of globals in testing. However, it does demonstrate that with globals, you retain some control — the ability to reset or replace the reference can serve as a temporary bandage.

The Singleton’s Downfall: A Refactoring Nightmare

A month passes and you get an angry message from Jerry that your tests are failing for his urgent pull request (PR) — and you need to fix them!

Looking at his PR, you discover that he changed the cache implementation from a simple dictionary to a dedicated AuthCache class, implemented as a singleton. This seemingly innocuous change, however, triggers a cascade of test failures.

Now the previously straightforward task of resetting the cache becomes a complex ordeal. The singleton’s private state is no longer easily accessible or replaceable. Attempts to manipulate the singleton’s internals through reflection or other invasive techniques undermine the very principles of encapsulation and abstraction that the refactor aimed to uphold.

The once-simple tests, designed to be independent and self-contained, now rely on intricate mocking or patching mechanisms to isolate the singleton’s effects. This increased complexity not only makes the tests harder to understand and maintain but also exposes the inherent fragility of singletons in a testing environment.

In this scenario, the singleton’s allure of simplicity and global accessibility has morphed into a testing nightmare. The very feature that made it convenient for sharing state across the application now hinders the ability to write reliable and maintainable tests. The singleton, initially intended to simplify the codebase, has become a source of complexity and frustration.

Dependency Injection: The Solution to Testing Woes

The root cause of these issues lies in the inherent statefulness of globals (and singletons especially). They violate the principle of isolation, making tests unpredictable and prone to failure. DI provides an elegant solution; by explicitly passing dependencies into objects, it thereby eliminates hidden state and ensures test isolation.

_default_auth_cache = AuthCache()
 
class App:
  def __init__(self, auth_cache: AuthCache = None, ...):
    self._auth_cache = auth_cache or _default_auth_cache
    # ...

# In your tests:
def test_user_authorized():
  app = App(auth_cache=AuthCache())  # Inject a fresh cache
  # ...
 
def test_user_unauthorized():
  app = App(auth_cache=AuthCache())  # Inject a fresh cache
  # ...

With DI, each test receives a fresh, isolated AuthCache instance, guaranteeing consistent and predictable behavior. This architectural shift not only strengthens your tests but also confers additional advantages:

• Enhanced modularity: DI promotes loose coupling between components, facilitating codebase evolution.
• Improved testability: Injecting mock dependencies simplifies unit testing by enabling isolated testing of individual components.
• Simplified configuration: Dependencies can be easily swapped or configured through injection.

Beyond Singletons: Embracing Flexibility and Control

The misconception that DI precludes true singletons is a common pitfall. In fact, DI offers greater flexibility, allowing for both single and multiple instances as needed. This adaptability proves invaluable in testing, enabling fine-grained control over scenarios and uncovering hidden interactions. While genuine singletons might be warranted in specific cases, DI frequently provides a more versatile and maintainable approach.

Conclusion

While singletons might seem enticing for managing shared resources, their inherent drawbacks can lead to brittle tests, complex refactoring scenarios and reduced code flexibility. Dependency injection, by contrast, fosters a more modular, testable and adaptable codebase. By embracing DI, you empower your software with the resilience and flexibility required to thrive in a constantly evolving environment.