Testresources: Unittest Extension for Resource Management

Common errors

• AttributeError: 'NoneType' object has no attribute 'some_method'

  cause A custom `TestResourceManager`'s `make()` method (or `getResource()` in older terms) returned `None`, which `testresources` doesn't inherently flag as an error, leading to tests trying to use a `None` object.
  fix Review your `TestResourceManager` implementation. Ensure its `make()` method always returns a valid, non-`None` object representing the resource, or explicitly raises an exception if the resource cannot be created.

• MyClass.setUpClass was never called / MyModule.setUpModule was never called

  cause You are using `OptimisingTestSuite` to run your tests, which flattens test suites and bypasses the `setUpClass` and `setUpModule` hooks from standard `unittest` classes.
  fix Refactor your class or module-level setup logic to be handled by a `testresources.TestResourceManager`. Define your resource manager, then declare it in your `ResourcedTestCase`'s `resources` attribute to leverage `testresources`'s optimized lifecycle management.

• Resource is re-created for every test despite using OptimisingTestSuite.

  cause The `testresources` framework re-creates or resets resources if it determines they are 'dirty'. This often happens if `TestResourceManager.isDirty()` is not correctly implemented or if `resource.dirtied()` is not called after a test modifies a shared resource.
  fix If your resource can be reused without full recreation, implement `isDirty(self, resource)` in your `TestResourceManager` to return `False` if the resource is in a reusable state. If tests modify the resource and it needs to be reset, call `self.resource_manager.dirtied(self.resource)` within the test method to signal a state change.

Warnings

• breaking When using `OptimisingTestSuite`, `unittest.TestCase.setUpClass` and `unittest.TestCase.setUpModule` are bypassed. The suite is flattened for resource optimization, meaning these class/module-level setup methods will not run.
  Fix: Migrate class/module-level resource setup to `testresources.TestResourceManager` implementations and declare them via the `resources` attribute of `ResourcedTestCase`.
• gotcha If a `TestResourceManager.make()` method successfully completes but returns `None`, `testresources` does not consider this an error. This can lead to `AttributeError` in tests attempting to use the `None` resource.
  Fix: Always ensure your `TestResourceManager.make()` method returns a valid, non-`None` resource object upon successful creation, or raises an appropriate exception if resource creation genuinely fails.
• gotcha Dynamically requesting resources inside a test method is generally discouraged. `testresources` is designed for statically declared resources to allow for optimal test ordering and resource reuse.
  Fix: Declare all necessary resources statically as class attributes of your `ResourcedTestCase` via the `resources` tuple. If a test needs sub-elements, let a statically declared resource provide methods to generate them.

Install

• pip install testresources Install latest version

Imports

• ResourcedTestCase

  from testresources import ResourcedTestCase

  Base class for test cases that declare and use shared resources.
• TestResourceManager

  from testresources import TestResourceManager

  Base class for defining custom resource managers (factories for resources).
• OptimisingTestSuite

  from testresources import OptimisingTestSuite

  A TestSuite that orders tests to minimize resource setup/teardown operations.
• TestResource

  from testresources import TestResource

  A simple base class for resource objects that need explicit make() and clean() methods.

Quickstart

This quickstart demonstrates how to define a shared resource (a simulated database connection) using `TestResource`, declare its usage within a `ResourcedTestCase`, and then execute tests efficiently with `OptimisingTestSuite` to minimize setup and teardown overhead.

import unittest
from testresources import TestResource, ResourcedTestCase, OptimisingTestSuite

# 1. Define your expensive resource and how to set it up/tear it down
class DatabaseResource(TestResource):
    def make(self):
        print("\n--- Creating database connection ---")
        # Simulate a database connection object
        self.connection = {'host': 'localhost', 'port': 5432, 'db': 'test'}
        return self.connection

    def clean(self, connection):
        print("--- Closing database connection ---")
        self.connection = None

    # Optional: Implement isDirty if the resource can become dirty and needs resetting
    # def isDirty(self, connection):
    #     return False # Assume it's always clean for this example

# Create a singleton instance of the resource manager
db_resource_manager = DatabaseResource()

# 2. Define your test case, inheriting from ResourcedTestCase
class MyDatabaseTest(ResourcedTestCase):
    # Declare the resources needed by tests in this class
    # The resource will be assigned to self.db_conn
    resources = [('db_conn', db_resource_manager)]

    def test_query_data(self):
        print(f"Test 1: Querying data with {self.db_conn}")
        self.assertIn('host', self.db_conn)

    def test_insert_data(self):
        print(f"Test 2: Inserting data with {self.db_conn}")
        # Simulate modifying the resource, then mark it dirty if necessary
        # db_resource_manager.dirtied(self.db_conn) # Uncomment if isDirty is implemented
        self.assertEqual(self.db_conn['db'], 'test')

    def test_another_query(self):
        print(f"Test 3: Another query with {self.db_conn}")
        self.assertTrue(self.db_conn['port'] == 5432)

# 3. Use OptimisingTestSuite to run your tests efficiently
if __name__ == '__main__':
    suite = unittest.TestSuite()
    suite.addTest(unittest.makeSuite(MyDatabaseTest))

    # Wrap the suite in OptimisingTestSuite
    optimised_suite = OptimisingTestSuite(suite)

    # Run the tests
    runner = unittest.TextTestRunner(verbosity=2)
    runner.run(optimised_suite)