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)[source]

Subclass of click.testing.CliRunner with extra features.

assert_exit_0(*args, **kwargs)[source]

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)[source]

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[source]

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)[source]

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.

message_ix_models.testing.mix_models_cli(request, session_context, tmp_env)[source]

A CliRunner object that invokes the mix-models CLI.

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

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)[source]

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)[source]

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)[source]

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

message_ix_models.testing.user_context(request)[source]

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