Test utilities and fixtures (testing)

Fixtures:

mix_models_cli(session_context, tmp_env)	A CliRunner object that invokes the mix-models CLI.
session_context(pytestconfig, tmp_env)	A Context connected to a temporary, in-memory database.
test_context(request, session_context)	A copy of session_context() scoped to one test function.
user_context(request)	Context which can access user's configuration, e.g.

Marks:

NIE	Shorthand for marking a parametrized test case that is expected to fail because it is not implemented.
not_ci([reason, action])	Mark a test as xfail or skipif if on CI infrastructure.

Others:

EXPORT_OMIT	Items with names that match (partially or fully) these names are omitted by export_test_data().
bare_res(request, context[, solved])	Return or create a Scenario containing the bare RES for use in testing.
export_test_data(context)	Export a subset of data from a scenario, for use in tests.
pytest_addoption(parser)	Add two command-line options to pytest:

message_ix_models.testing.EXPORT_OMIT = ['aeei', 'cost_MESSAGE', 'demand_MESSAGE', 'demand', 'depr', 'esub', 'gdp_calibrate', 'grow', 'historical_gdp', 'kgdp', 'kpvs', 'lakl', 'land', 'lotol', 'mapping_macro_sector', 'MERtoPPP', 'prfconst', 'price_MESSAGE', 'ref_', 'sector']

Items with names that match (partially or fully) these names are omitted by export_test_data().

message_ix_models.testing.GHA = False

True if tests occur on GitHub Actions.

message_ix_models.testing.NIE = MarkDecorator(mark=Mark(name='xfail', args=(), kwargs={'raises': <class 'NotImplementedError'>}))

Shorthand for marking a parametrized test case that is expected to fail because it is not implemented.

message_ix_models.testing.bare_res(request, context: Context, solved: bool = False) → Scenario

Return or create a Scenario containing the bare RES for use in testing.

The Scenario has a model name like “MESSAGEix-GLOBIOM [regions] Y[years]”, for instance “MESSAGEix-GLOBIOM R14 YB” (see bare.name()) and a scenario name either from request.node.name or “baseline” plus a random string.

This function should:

• only be called from within test code, i.e. in message_data.tests.

• be called once for each test function, so that each test receives a fresh copy of the RES scenario.

Parameters:

• request (FixtureRequest or None) – The pytest request fixture. If provided the pytest test node name is used for the scenario name of the returned Scenario.

• context (Context) – Passed to testing.bare_res().

• solved (bool, optional) – Return a solved Scenario.

Returns:

The scenario is a fresh clone, so can be modified freely without disturbing other tests.

Return type:

Scenario

message_ix_models.testing.export_test_data(context: Context)

Export a subset of data from a scenario, for use in tests.

The context settings export_nodes (default: “R11_AFR” and “R11_CPA”) and export_techs (default: “coal_ppl”) are used to filter the data exported. In addition, any item (set, parameter, variable, or equation) with a name matching EXPORT_OMIT or the context setting export_exclude is discarded.

The output is stored at data/tests/model name_scenario name_techs.xlsx in message_data.

See also

Prepare data for testing

message_ix_models.testing.mix_models_cli(session_context, tmp_env)

A CliRunner object that invokes the mix-models CLI.

NB this requires:

• The ixmp tmp_env() fixture. This sets IXMP_DATA to a temporary directory managed by pytest.

• The session_context() fixture. This (a) sets Config.local_data to a temporary directory within IXMP_DATA and (b) ensures changes to Context made by invoked commands do not reach other tests.

message_ix_models.testing.not_ci(reason=None, action='skip')

Mark a test as xfail or skipif if on CI infrastructure.

Checks the GITHUB_ACTIONS environment variable; returns a pytest mark.

message_ix_models.testing.preserve_report_callbacks()

Protect report.CALLBACKS from effects of a test function.

Use this fixture for test functions that call report.register() to avoid changing the global/default configuration for other tests.

message_ix_models.testing.pytest_addoption(parser)

Add two command-line options to pytest:

--local-cache

Use existing, local cache files in tests. This option can speed up tests that use the results of slow data loading/parsing. However, if cached values are not up to date with the current code, unexpected failure may occur.

--jvmargs

Additional arguments to give for the Java Virtual Machine used by ixmp’s JDBCBackend. Used by session_context().

message_ix_models.testing.session_context(pytestconfig, tmp_env)

A Context connected to a temporary, in-memory database.

This Context is suitable for modifying and running test code that does not affect the user/developer’s filesystem and configured ixmp databases.

Uses the tmp_env() fixture from ixmp. This fixture also sets:

• Config.cache_path, depending on whether the --local-cache CLI option was given:

  • If not given: pytest’s standard cache directory.

  • If given: the /cache/ directory under the user’s “message local data” directory.

• the “message local data” config key to a temporary directory /data/ under the pytest tmp_path directory.

message_ix_models.testing.test_context(request, session_context)

A copy of session_context() scoped to one test function.

message_ix_models.testing.unpack_snapshot_data(context: Context, snapshot_id: int)

Already-unpacked data for a snapshot.

This copies the .csv.gz files from message_ix_models/data/test/… to the directory where they would be unpacked by .model.snapshot._unpack. This causes the code to skip unpacking them, which can be very slow.

message_ix_models.testing.user_context(request)

Context which can access user’s configuration, e.g. platform names.