Test utilities and fixtures (testing)

Fixtures:

mix_models_cli(request, 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().
CliRunner([charset, env, echo_stdin, mix_stderr])	Subclass of click.testing.CliRunner with extra features.
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:

class message_ix_models.testing.CliRunner(charset: str = 'utf-8', env: Mapping[str, str | None] | None = None, echo_stdin: bool = False, mix_stderr: bool = True)

Subclass of click.testing.CliRunner with extra features.

assert_exit_0(*args, **kwargs)

Assert a result has exit_code 0, or print its traceback.

If any args or kwargs are given, invoke() is first called. Otherwise, the result from the last call of invoke() is used.

Raises:

AssertionError – if the result exit code is not 0. The exception contains the traceback from within the CLI.

Return type:

click.testing.Result

invoke(*args, **kwargs)

Invoke the mix-models CLI.

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] [start]:[duration]:[end]”, e.g. “MESSAGEix-GLOBIOM R14 2020:10:2110” (see bare.name()) and the scenario name “baseline”.

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 (.Request 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(request, session_context, tmp_env)

A CliRunner object that invokes the mix-models CLI.

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.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:

• Context.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.user_context(request)

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