ScopedSingletonState

RAII class for temporarily replacing singleton instances during testing.

Overview

Overview
Usage

Public Methods

ScopedSingletonState()
~ScopedSingletonState()
instance()

Overview

PM::ScopedSingletonState<T> is an RAII (Resource Acquisition Is Initialization) class that temporarily replaces the singleton instance of type T with a new instance. This class is specifically designed for testing purposes, enabling isolated singleton state management without affecting the global singleton state in other parts of the application.

The class works by storing the current singleton instance pointer upon construction and replacing it with a new instance. Upon destruction (when the scoped object goes out of scope), it automatically restores the original singleton instance. This ensures that test code can modify singleton state locally without side effects on other tests or the main application.

This RAII pattern guarantees that the singleton state is always properly restored, even if exceptions occur during testing. The class provides direct access to the temporary instance for modification during tests.

Note: The template parameter T must be a type that publicly inherits from SingletonBase.

Usage

Basic Test Isolation

The most common usage is to add a ScopedSingletonState at the beginning of each test case function to ensure each test gets a fresh, unmodified singleton instance. This prevents test interference and ensures predictable test behavior.

#include <PM/ScopedSingletonState.h>

void testSingleton() {
    // Create scoped state at test start for isolation
    PM::ScopedSingletonState<MySingleton> scoped;
    
    // MySingleton::instance() now returns a new, blank instance
    MySingleton::instance().setTestValue(42);
    
    // Test logic here...
    assert(MySingleton::instance().getValue() == 42);
}
// Original instance automatically restored when test ends

Nested Scopes

For more granular control, create the scoped state within a nested scope to limit its effect to only a specific portion of the test code. This allows testing different singleton states within the same test function.

void testWithNestedScopes() {
    MySingleton::instance().setValue(100); // Global instance
    
    {
        PM::ScopedSingletonState<MySingleton> innerScope;
        // Only this block sees the new instance
        assert(MySingleton::instance().getValue() != 100);
        innerScope.instance().setValue(200);
        assert(MySingleton::instance().getValue() == 200);
    }
    
    // Back to global instance
    assert(MySingleton::instance().getValue() == 100);
}

Mocking with Derived Types

Create a ScopedSingletonState with a template parameter of a derived type from the original singleton class. This enables testing with mock implementations while maintaining the same interface.

class MockSingleton : public MySingleton {
public:
    void setMockBehavior() { /* mock-specific setup */ }
};

void testWithMock() {
    PM::ScopedSingletonState<MockSingleton> mockScope;
    
    // MySingleton::instance() now returns the mock
    auto& mock = mockScope.instance();
    mock.setMockBehavior();
    
    // Test code interacts with mock through normal interface
    assert(MySingleton::instance().someMethod() == mockResult);
}

See also: Advanced Topics for detailed exploration of these usage patterns and best practices.

Public_Methods