def test_clone(self):
"""Testing DatabaseState.clone"""
database_state = DatabaseState(db_name='default')
cloned_state = database_state.clone()
self.assertEqual(cloned_state.db_name, database_state.db_name)
self.assertEqual(cloned_state._tables, database_state._tables)
def test_clone(self):
"""Testing DatabaseState.clone"""
database_state = DatabaseState(db_name='default')
cloned_state = database_state.clone()
self.assertEqual(cloned_state.db_name, database_state.db_name)
self.assertEqual(cloned_state._tables, database_state._tables)
class EvolutionTestCase(TestCase):
"""Base class for test cases that need to evolve the database."""
default_model_name = 'TestModel'
default_base_model = None
default_pre_extra_models = []
default_extra_models = []
def setUp(self):
super(EvolutionTestCase, self).setUp()
self.base_model = None
self.pre_extra_models = []
self.extra_models = []
self.start = None
self.start_sig = None
self.database_state = None
self.test_database_state = None
self._models_registered = False
if self.default_base_model:
self.set_base_model(base_model=self.default_base_model,
pre_extra_models=self.default_pre_extra_models,
extra_models=self.default_extra_models)
def tearDown(self):
if self._models_registered:
unregister_app('tests')
super(EvolutionTestCase, self).tearDown()
def default_create_test_data(self, db_name):
"""Default function for creating test data for base models.
By default, this won't do anything.
Args:
db_name (unicode):
The name of the database to create models on.
"""
pass
def set_base_model(self,
base_model,
name=None,
extra_models=[],
pre_extra_models=[],
db_name=None):
"""Set the base model(s) that will be mutated in a test.
These models will be registered in Django's model registry and
queued up to be written to the database. Starting signatures based
on these models will be provided, which the test is expected to
mutate.
Args:
base_model (type):
The base :py:class:`~django.db.models.Model` to register and
write to the database that the test will then mutate.
name (unicode, optional):
The name to register for the model. This defaults to
:py:attr:`default_model_name`.
extra_models (list of type, optional):
The list of extra models to register and write to the
database after writing ``base_model``. These may form
relations to ``base_model``.
pre_extra_models (list of type, optional):
The list of extra models to write to the database before
writing ``base_model``. ``base_model`` may form relations to
these models.
db_name (unicode, optional):
The name of the database to write the models to. This
defaults to :py:attr:`default_database_name`.
"""
name = name or self.default_model_name
db_name = db_name or self.default_database_name
if self.base_model:
unregister_app('tests')
self.base_model = base_model
self.pre_extra_models = pre_extra_models
self.extra_models = extra_models
self.database_state = DatabaseState(db_name)
self.start = self.register_model(model=base_model,
name=name,
register_indexes=True,
db_name=db_name)
self.start_sig = self.create_test_proj_sig(model=base_model, name=name)
def make_end_signatures(self, dest_model, model_name, db_name=None):
"""Return signatures for a model representing the end of a mutation.
Callers should construct a model that reflects the expected result
of any mutations and provide that. This will register that model
and construct a signature from it.
Args:
dest_model (type):
The destination :py:class:`~django.db.models.Model`
representing the expected result of an evolution.
model_name (unicode):
The name to register for the model.
db_name (unicode, optional):
The name of the database to write the models to. This
defaults to :py:attr:`default_database_name`.
Returns:
tuple:
A tuple containing:
1. A :py:class:`collections.OrderedDict` mapping the model name
to the model class.
2. A :py:class:`django_evolution.signature.ProjectSignature`
for the provided model.
"""
db_name = db_name or self.default_database_name
end = self.register_model(model=dest_model,
name=model_name,
db_name=db_name)
end_sig = self.create_test_proj_sig(model=dest_model, name=model_name)
return end, end_sig
def perform_evolution_tests(self,
dest_model,
evolutions,
diff_text=None,
expected_hint=None,
sql_name=None,
model_name=None,
end=None,
end_sig=None,
expect_noop=False,
rescan_indexes=True,
use_hinted_evolutions=False,
perform_simulations=True,
perform_mutations=True,
db_name=None,
create_test_data_func=None):
"""Perform test evolutions and validate results.
This is used for most common evolution-related tests. It handles
generating signatures for a base model and an expected post-evolution
model, ensuring that the mutations result in an empty diff.
It then optionally simulates the evolutions on the signatures
(using :py:meth:`perform_simulations)`, and then optionally performs
the actual evolutions on the database (using
:py:meth:`perform_mutations`), verifying all results.
Args:
dest_model (type):
The destination :py:class:`~django.db.models.Model`
representing the expected result of an evolution.
evolutions (list of django_evolution.mutations.BaseMutation):
The combined series of evolutions (list of mutations) to apply
to the base model.
diff_text (unicode, optional):
The expected generated text describing a diff that must
match, if provided.
expected_hint (unicode, optional):
The expected generated hint text that must match, if provided.
sql_name (unicode, optional):
The name of the registered SQL content for the database being
tested.
This must be provided if ``perform_mutations`` is ``True`.
model_name (unicode, optional):
The name of the model to register. This defaults to
:py:attr:`default_model_name`.
end (collections.OrderedDict, optional):
The expected model map at the end of the evolution. This
is generated by :py:meth:`make_end_signatures`.
If not provided, one will be generated.
end_sig (django_evolution.signature.ProjectSignature, optional):
The expected project signature at the end of the evolution.
This is generated by :py:meth:`make_end_signatures`.
If not provided, one will be generated.
expect_noop (bool, optional):
Whether the evolution is expected not to change anything.
rescan_indexes (bool, optional):
Whether to re-scan the list of table indexes after performing
mutations.
This is ignored if ``perform_mutations`` is ``False``.
use_hinted_evolutions (bool, optional):
Whether to use the hinted evolutions generated by the
signatures. This cannot be used if ``evolutions`` is
non-empty.
perform_simulations (bool, optional):
Whether to simulate the evolution and compare results.
perform_mutations (bool, optional):
Whether to apply the mutations and compare results.
db_name (unicode, optional):
The name of the database to apply evolutions to. This
defaults to :py:attr:`default_database_name`.
create_test_data_func (callable, optional):
A function to call in order to create data in the database for
the initial models, before applying mutations. It must take
a database name.
If not provided, :py:meth:`default_create_test_data` will be
used.
Raises:
AssertionError:
A diff, simulation, or mutation test has failed.
"""
model_name = model_name or self.default_model_name
db_name = db_name or self.default_database_name
if end is None or end_sig is None:
end, end_sig = self.make_end_signatures(dest_model=dest_model,
model_name=model_name,
db_name=db_name)
# See if the diff between signatures contains the contents we expect.
d = self.perform_diff_test(end_sig=end_sig,
diff_text=diff_text,
expected_hint=expected_hint,
expect_empty=expect_noop)
if use_hinted_evolutions:
assert not evolutions, (
'The evolutions= argument cannot be provided when providing '
'use_hinted_evolutions=True')
evolutions = d.evolution()['tests']
if perform_simulations:
self.perform_simulations(evolutions=evolutions,
end_sig=end_sig,
db_name=db_name)
if perform_mutations:
self.perform_mutations(
evolutions=evolutions,
end=end,
end_sig=end_sig,
sql_name=sql_name,
rescan_indexes=rescan_indexes,
db_name=db_name,
create_test_data_func=(create_test_data_func
or self.default_create_test_data))
def perform_diff_test(self,
end_sig,
diff_text=None,
expected_hint=None,
expect_empty=False):
"""Generate a diff between signatures and check for expected results.
The registered base signature and the provided ending signature will
be diffed, asserted to be empty/not empty (depending on the arguments),
and then checked against the provided diff text and hint.
Args:
end_sig (django_evolution.signature.ProjectSignature):
The expected project signature at the end of the evolution.
This is generated by :py:meth:`make_end_signatures`.
diff_text (unicode, optional):
The expected generated text describing a diff that must
match, if provided.
expected_hint (unicode, optional):
The expected generated hint text that must match, if provided.
expect_empty (bool, optional):
Whether the diff is expected to be empty.
Returns:
django_evolution.diff.Diff:
The resulting diff.
Raises:
AssertionError:
One of the expectations has failed.
"""
d = Diff(self.start_sig, end_sig)
self.assertEqual(d.is_empty(), expect_empty)
if not expect_empty:
if diff_text is not None:
self.assertEqual(str(d), diff_text)
if expected_hint is not None:
self.assertEqual([str(e) for e in d.evolution()['tests']],
expected_hint)
return d
def perform_simulations(self,
evolutions,
end_sig,
ignore_apps=False,
db_name=None):
"""Run simulations and verify that they result in an end signature.
This will run through an evolution chain, simulating each one on a
copy of the starting signature, and then verifying that the signature
is properly transformed into the expected ending signature.
Args:
evolutions (list of django_evolution.mutations.BaseMutation):
The evolution chain to run simulations on.
end_sig (django_evolution.signature.ProjectSignature):
The expected ending signature.
ignore_apps (bool, optional):
Whether to ignore changes to the list of applications.
db_name (unicode, optional):
The name of the database to perform the simulations against.
Returns:
django_evolution.signature.ProjectSignature:
The resulting modified signature.
Raises:
AssertionError:
The modified signature did not match the expected end
signature.
"""
db_name = db_name or self.default_database_name
self.test_database_state = self.database_state.clone()
test_sig = self.start_sig.clone()
for mutation in evolutions:
mutation.run_simulation(app_label='tests',
project_sig=test_sig,
database_state=self.test_database_state,
database=db_name)
# Check that the simulation's changes results in an empty diff.
d = Diff(test_sig, end_sig)
self.assertTrue(d.is_empty(ignore_apps=ignore_apps))
return test_sig
def perform_mutations(self,
evolutions,
end,
end_sig,
sql_name=None,
rescan_indexes=True,
db_name=None,
create_test_data_func=None):
"""Apply mutations that and verify the results.
This will run through the evolution chain, applying each mutation
on the database and against the signature, and then verifying the
resulting signature and generated SQL.
Args:
evolutions (list of django_evolution.mutations.BaseMutation):
The evolution chain to run simulations on.
end (collections.OrderedDict):
The expected model map at the end of the evolution. This
is generated by :py:meth:`make_end_signatures`.
end_sig (django_evolution.signature.ProjectSignature):
The expected ending signature. This is generated by
:py:meth:`make_end_signatures`.
sql_name (unicode, optional):
The name of the registered SQL content for the database being
tested. If not provided, the SQL won't be compared.
rescan_indexes (bool, optional):
Whether to re-scan the list of table indexes after applying
the mutations.
db_name (unicode, optional):
The name of the database to apply the evolutions against.
create_test_data_func (callable, optional):
A function to call in order to create data in the database for
the initial models, before applying mutations. It must take
a database name.
Raises:
AssertionError:
The resulting SQL did not match.
django.db.utils.OperationalError:
There was an error executing SQL.
"""
app_label = 'tests'
def run_mutations():
if rescan_indexes:
self.test_database_state.rescan_tables()
app_mutator = AppMutator(app_label=app_label,
project_sig=test_sig,
database_state=self.test_database_state,
database=db_name)
app_mutator.run_mutations(evolutions)
return app_mutator.to_sql()
db_name = db_name or self.default_database_name
self.test_database_state = self.database_state.clone()
test_sig = self.start_sig.clone()
with ensure_test_db(model_entries=six.iteritems(self.start),
end_model_entries=six.iteritems(end),
app_label=app_label,
database=db_name):
if create_test_data_func:
create_test_data_func(db_name)
sql = execute_test_sql(run_mutations(), database=db_name)
if sql_name is not None:
self.assertSQLMappingEqual(sql, sql_name, database=db_name)
def register_model(self, model, name, db_name=None, **kwargs):
"""Register a model for the test.
This will register not only this model, but any models in
:py:attr:`pre_extra_models` and :py:attr:`extra_models`. It will
not include :py:attr:`base_model`.
Args:
model (type):
The main :py:class:`~django.db.models.Model` to register.
name (unicode):
The name to use when for the model when registering. This
doesn't have to match the model's actual name.
db_name (unicode, optional):
The name of the database to register this model on.
**kwargs (dict):
Additional keyword arguments to pass to
:py:func:`~django_evolution.tests.utils.register_models`.
Returns:
collections.OrderedDict:
A dictionary of registered models. The keys are model names, and
the values are the models.
"""
self._models_registered = True
models = self.pre_extra_models + [(name, model)] + self.extra_models
return register_models(database_state=self.database_state,
models=models,
new_app_label='tests',
db_name=db_name or self.default_database_name,
**kwargs)
def create_test_proj_sig(self,
model,
name,
extra_models=[],
pre_extra_models=[]):
"""Create a project signature for the given models.
The signature will include not only these models, but any models in
:py:attr:`pre_extra_models` and :py:attr:`extra_models`. It will
not include :py:attr:`base_model`.
Args:
model (type):
The main :py:class:`~django.db.models.Model` to include
in the signature.
name (unicode):
The name to use when for the model. This doesn't have to match
the model's actual name.
extra_models (list of type, optional):
An additional list of extra models to register after ``model``
(but before the class-defined :py:attr:`extra_models`).
pre_extra_models (list of type, optional):
An additional list of extra models to register before ``model``
(but after :py:attr:`pre_extra_models`).
Returns:
django_evolution.signature.ProjectSignature:
The generated project signature.
"""
return create_test_project_sig(
models=(self.pre_extra_models + pre_extra_models +
[(name, model)] + extra_models + self.extra_models))
def copy_models(self, models):
"""Copy a list of models.
This will be a deep copy, allowing any of the copied models to be
altered without affecting the originals.
Args:
models (list of type):
The list of :py:class:`~django.db.models.Model` classes.
Returns:
list of type:
The copied list of :py:class:`~django.db.models.Model` classes.
"""
return copy.deepcopy(models)
@contextmanager
def override_db_routers(self, routers):
"""Override database routers for a test.
This clears the router cache before and after the test, allowing
custom routers to be used during unit tests.
Args:
routers (list):
The list of router class paths or instances.
Yields:
The context.
"""
try:
with override_settings(DATABASE_ROUTERS=routers):
self.clear_routers_cache()
yield
finally:
self.clear_routers_cache()
def clear_routers_cache(self):
"""Clear the router cache."""
router.routers = ConnectionRouter().routers
class EvolutionTestCase(TestCase):
"""Base class for test cases that need to evolve the database."""
sql_mapping_key = None
default_database_name = 'default'
default_model_name = 'TestModel'
default_base_model = None
default_pre_extra_models = []
default_extra_models = []
# Allow for diffs for large dictionary structures, to help debug
# signature failures.
maxDiff = 10000
def setUp(self):
self.base_model = None
self.pre_extra_models = []
self.extra_models = []
self.start = None
self.start_sig = None
self.database_state = None
self.test_database_state = None
self._models_registered = False
if self.default_base_model:
self.set_base_model(self.default_base_model,
pre_extra_models=self.default_pre_extra_models,
extra_models=self.default_extra_models)
def tearDown(self):
if self._models_registered:
unregister_app('tests')
def set_base_model(self, model, name=None, extra_models=[],
pre_extra_models=[], db_name=None):
name = name or self.default_model_name
db_name = db_name or self.default_database_name
if self.base_model:
unregister_app('tests')
self.base_model = model
self.pre_extra_models = pre_extra_models
self.extra_models = extra_models
self.database_state = DatabaseState(db_name)
self.start = self.register_model(model, name,
register_indexes=True,
db_name=db_name)
self.start_sig = self.create_test_proj_sig(model, name)
def make_end_signatures(self, model, model_name, db_name=None):
db_name = db_name or self.default_database_name
end = self.register_model(model, name=model_name, db_name=db_name)
end_sig = self.create_test_proj_sig(model, name=model_name)
return end, end_sig
def perform_evolution_tests(self, model, evolutions, diff_text=None,
expected_hint=None, sql_name=None,
model_name=None,
end=None, end_sig=None,
expect_noop=False,
rescan_indexes=True,
use_hinted_evolutions=False,
perform_simulations=True,
perform_mutations=True,
db_name=None):
model_name = model_name or self.default_model_name
db_name = db_name or self.default_database_name
if end is None or end_sig is None:
end, end_sig = self.make_end_signatures(model, model_name, db_name)
# See if the diff between signatures contains the contents we expect.
d = self.perform_diff_test(end_sig, diff_text, expected_hint,
expect_empty=expect_noop)
if use_hinted_evolutions:
assert not evolutions
evolutions = d.evolution()['tests']
if perform_simulations:
self.perform_simulations(evolutions, end_sig, db_name=db_name)
if perform_mutations:
self.perform_mutations(evolutions, end, end_sig, sql_name,
rescan_indexes=rescan_indexes,
db_name=db_name)
def perform_diff_test(self, end_sig, diff_text, expected_hint,
expect_empty=False):
d = Diff(self.start_sig, end_sig)
self.assertEqual(d.is_empty(), expect_empty)
if not expect_empty:
if diff_text is not None:
self.assertEqual(str(d), diff_text)
if expected_hint is not None:
self.assertEqual(
[str(e) for e in d.evolution()['tests']],
expected_hint)
return d
def perform_simulations(self, evolutions, end_sig, ignore_apps=False,
db_name=None):
db_name = db_name or self.default_database_name
self.test_database_state = self.database_state.clone()
test_sig = self.start_sig.clone()
for mutation in evolutions:
mutation.run_simulation(app_label='tests',
project_sig=test_sig,
database_state=self.test_database_state,
database=db_name)
# Check that the simulation's changes results in an empty diff.
d = Diff(test_sig, end_sig)
self.assertTrue(d.is_empty(ignore_apps=ignore_apps))
def perform_mutations(self, evolutions, end, end_sig, sql_name,
rescan_indexes=True, db_name=None):
def run_mutations():
if rescan_indexes:
self.test_database_state.rescan_indexes()
app_mutator = AppMutator(app_label='tests',
project_sig=test_sig,
database_state=self.test_database_state,
database=db_name)
app_mutator.run_mutations(evolutions)
return app_mutator.to_sql()
db_name = db_name or self.default_database_name
self.test_database_state = self.database_state.clone()
test_sig = self.start_sig.clone()
sql = execute_test_sql(self.start, end, run_mutations,
database=db_name)
if sql_name is not None:
# Normalize the generated and expected SQL so that we are
# guaranteed to have a list with one item per line.
generated_sql = '\n'.join(sql).splitlines()
expected_sql = self.get_sql_mapping(sql_name, db_name).splitlines()
# Output the statements one-by-one, to help with diagnosing
# differences.
print()
print("** Comparing SQL against '%s'" % sql_name)
print('** Generated:')
print()
for line in generated_sql:
print(' %s' % line)
print()
print('** Expected:')
print()
for line in expected_sql:
print(' %s' % line)
print()
# Compare as lists, so that we can better spot inconsistencies.
self.assertListEqual(generated_sql, expected_sql)
def get_sql_mapping(self, name, db_name=None):
db_name = db_name or self.default_database_name
return get_sql_mappings(self.sql_mapping_key, db_name)[name]
def register_model(self, model, name, db_name=None, **kwargs):
self._models_registered = True
models = self.pre_extra_models + [(name, model)] + self.extra_models
return register_models(database_state=self.database_state,
models=models,
new_app_label='tests',
db_name=db_name or self.default_database_name,
**kwargs)
def create_test_proj_sig(self, model, name, extra_models=[],
pre_extra_models=[]):
return create_test_project_sig(models=(
self.pre_extra_models + pre_extra_models + [(name, model)] +
extra_models + self.extra_models
))
def copy_models(self, models):
return copy.deepcopy(models)
@contextmanager
def override_db_routers(self, routers):
"""Override database routers for a test.
This clears the router cache before and after the test, allowing
custom routers to be used during unit tests.
Args:
routers (list):
The list of router class paths or instances.
Yields:
The context.
"""
with override_settings(DATABASE_ROUTERS=routers):
self.clear_routers_cache()
yield
self.clear_routers_cache()
def clear_routers_cache(self):
"""Clear the router cache."""
router.routers = ConnectionRouter().routers