tests package

Submodules

tests.conftest module

Fixtures, configuration and helpers for tests.

tests.conftest.skip_windows_colors(*args, **kwargs) = MarkDecorator(mark=Mark(name='skipif', args=(<extra_platforms.pytest.DeferredCondition object>,), kwargs={'reason': 'Click overstrip colors on Windows'}))

Skips color tests on Windows as click.testing.invoke overzealously strips colors.

See: - https://github.com/pallets/click/issues/2111 - https://github.com/pallets/click/issues/2110

class tests.conftest.FormatType(*values)

Bases: Enum

Sphinx document format types and their file extensions.

RST = '.rst'

MYST = '.md'

class tests.conftest.SphinxAppWrapper(app, format_type)

Bases: object

Wrapper around Sphinx application with additional testing methods.

classmethod create(format_type, tmp_path, return_srcdir=False)

Factory method to create a SphinxAppWrapper with given format.

Return type:

Generator[SphinxAppWrapper | tuple[SphinxAppWrapper, Path], None, None]

build_document(content)

Build a Sphinx document with content and return the HTML output.

Automatically detects the format from the app configuration and uses the appropriate file extension (.rst or .md).

Return type:

str | None

generate_test_content(test_case)

Generate content for a test case based on the app’s format type.

Return type:

str

tests.conftest.sphinx_app(request, tmp_path)

Create a Sphinx application for testing.

tests.conftest.sphinx_app_rst(tmp_path)

Create a Sphinx application for testing RST format only.

tests.conftest.sphinx_app_myst(tmp_path)

Create a Sphinx application for testing MyST format only.

tests.conftest.sphinx_app_myst_with_include(tmp_path)

Create a Sphinx application for testing MyST format with include files.

class tests.conftest.DirectiveTestCase(name, format_type=None, source_block=None, run_block=None, document=None, html_matches=None)

Bases: object

Test case data for directive tests.

name: str

format_type: FormatType | None = None

source_block: str | None = None

run_block: str | None = None

document: str | None = None

html_matches: Sequence[str] | str | None = None

supports_format(format_type)

Check if this test case supports the given format type.

Todo

Get rid of this method, and make the test case provide its own sphinx_app.

Return type:

bool

tests.conftest.python_block(*lines)

Build expected Python highlight block.

Return type:

str

tests.conftest.shell_block(*lines)

Build expected shell session block.

Return type:

str

tests.conftest.admonition_block(admonition_type, content)

Build expected admonition block.

Return type:

str

Args:

admonition_type: The type of admonition (note, tip, warning, etc.) content: The inner HTML content of the admonition (without the title)

tests.test_colorize module

tests.test_colorize.test_theme_definition()

Ensure we do not leave any property we would have inherited from cloup and logging primitives.

tests.test_colorize.test_extra_theme()

class tests.test_colorize.HashType(*values)

Bases: Enum

MD5 = 1

SHA1 = 2

BCRYPT = 3

tests.test_colorize.test_option_highlight(opt, expected_outputs)

Test highlighting of all option’s variations.

tests.test_colorize.test_skip_hidden_option()

Ensure hidden options are not highlighted.

tests.test_colorize.test_only_full_word_highlight()

tests.test_colorize.test_keyword_collection(invoke, assert_output_regex)

tests.test_colorize.test_standalone_color_option(invoke, option_decorator, param, expecting_colors, assert_output_regex)

Check color option values, defaults and effects on all things colored, including verbosity option.

tests.test_colorize.test_no_color_env_convention(invoke, env, env_expect_colors, param, param_expect_colors)

tests.test_colorize.test_integrated_color_option(invoke, param, expecting_colors, assert_output_regex)

Check effect of color option on all things colored, including verbosity option.

Also checks the color option in subcommands is inherited from parent context.

tests.test_colorize.test_substring_highlighting(content, patterns, expected, ignore_case)

tests.test_colorize.test_standalone_help_option(invoke, cmd_decorator, cmd_type, option_decorator)

tests.test_commands module

Test defaults of our custom commands, as well as their customizations and attached options, and how they interact with each others.

tests.test_commands.test_module_root_declarations()

tests.test_commands.all_command_cli()

A CLI that is mixing all variations and flavors of subcommands.

tests.test_commands.test_unknown_option(invoke, all_command_cli)

tests.test_commands.test_unknown_command(invoke, all_command_cli)

tests.test_commands.test_required_command(invoke, all_command_cli, assert_output_regex)

tests.test_commands.test_group_help(invoke, all_command_cli, param, exit_code, assert_output_regex)

tests.test_commands.test_help_eagerness(invoke, all_command_cli, params, exit_code, expect_help, expect_empty_stderr, assert_output_regex)

See: https://click.palletsprojects.com/en/stable/advanced/#callback-evaluation-order

tests.test_commands.test_help_custom_name(invoke)

Removes the -h short option as we reserve it for a custom -h/--header option.

See: https://github.com/kdeldycke/mail-deduplicate/issues/762

tests.test_commands.test_subcommand_help(invoke, all_command_cli, cmd_id, param, assert_output_regex)

tests.test_commands.test_subcommand_execution(invoke, all_command_cli, cmd_id)

tests.test_commands.test_integrated_version_value(invoke, all_command_cli)

tests.test_commands.test_colored_bare_help(invoke, cmd_decorator, param)

Extra decorators are always colored.

Even when stripped of their default parameters, as reported in: https://github.com/kdeldycke/click-extra/issues/534 https://github.com/kdeldycke/click-extra/pull/543

tests.test_commands.test_duplicate_option(invoke)

See: - https://kdeldycke.github.io/click-extra/commands.html#change-default-options - https://github.com/kdeldycke/click-extra/issues/232

tests.test_commands.test_no_option_leaks_between_subcommands(invoke, assert_output_regex)

As reported in https://github.com/kdeldycke/click-extra/issues/489.

tests.test_commands.test_option_group_integration(invoke, assert_output_regex)

tests.test_commands.test_show_envvar_parameter(invoke, cmd_decorator, ctx_settings, expected_help)

tests.test_commands.test_raw_args(invoke)

Raw args are expected to be scoped in subcommands.

tests.test_commands.test_lazy_group(invoke, tmp_path, lazy_cmd_decorator)

Test extends the snippet from Click documentation.

tests.test_commands.test_decorator_overrides()

Ensure our decorators are not just alias of Click and Cloup ones.

tests.test_commands.test_decorator_cls_parameter(klass, should_raise)

Decorators accept custom cls parameters.

tests.test_config module

tests.test_config.simple_config_cli()

tests.test_config.test_unset_conf(invoke, simple_config_cli)

tests.test_config.test_unset_conf_debug_message(invoke, simple_config_cli, assert_output_regex)

tests.test_config.test_conf_default_path(invoke, simple_config_cli)

tests.test_config.test_conf_default_pathlib_type(invoke, create_config)

Refs https://github.com/kdeldycke/click-extra/issues/1356

tests.test_config.test_conf_not_exist(invoke, simple_config_cli)

tests.test_config.test_conf_not_file(invoke, simple_config_cli)

tests.test_config.test_no_config_option(invoke, simple_config_cli, create_config)

tests.test_config.test_standalone_no_config_option(invoke)

@no_config_option cannot work without @config_option.

tests.test_config.test_strict_conf(invoke, create_config)

Same test as the one shown in the readme, but in strict validation mode.

tests.test_config.test_conf_file_overrides_defaults(invoke, simple_config_cli, create_config, httpserver, conf_name, conf_text, conf_data, assert_output_regex)

tests.test_config.test_auto_envvar_conf(invoke, simple_config_cli, create_config, httpserver, conf_name, conf_text, conf_data)

tests.test_config.test_conf_file_overridden_by_cli_param(invoke, simple_config_cli, create_config, httpserver, conf_name, conf_text, conf_data)

tests.test_config.test_conf_metadata(invoke, create_config, httpserver, conf_name, conf_text, conf_data)

tests.test_config.test_multiple_cli_shared_conf(invoke, create_config)

Two CLIs sharing the same configuration file.

Refs: https://github.com/kdeldycke/click-extra/issues/1277

tests.test_config.test_file_pattern(file_format_patterns, expected_pattern)

Test the file_pattern property with different file format configurations.

tests.test_config.test_default_pattern_roaming_force_posix(roaming, force_posix, current_platform, expected_path)

Test that roaming and force_posix affect the default pattern generation.

tests.test_envvar module

tests.test_envvar.test_merge_envvar_ids(envvars, result)

tests.test_envvar.test_clean_envvar_id(env_name, clean_name)

tests.test_envvar.test_show_auto_envvar_help(invoke, cmd_decorator, option_help)

Check that the auto-generated envvar appears in the help screen with the extra variants.

Checks that https://github.com/pallets/click/issues/2483 is addressed.

tests.test_envvar.envvars_test_cases()

tests.test_envvar.test_auto_envvar_parsing(invoke, cmd_decorator, envvars, expected_flag)

This test highlights the way Click recognize and parse envvars.

It shows that the default behavior is not ideal, and covers how command improves the situation by normalizing the envvar name.

tests.test_envvar.test_env_copy()

tests.test_logging module

tests.test_logging.test_level_default_order()

tests.test_logging.test_root_logger_defaults()

Check our internal default is aligned to Python’s root logger.

tests.test_logging.test_integrated_verbosity_options(invoke, args, expected_level, assert_output_regex)

tests.test_logging.test_custom_verbosity_option_name(invoke, args, assert_output_regex)

tests.test_logging.test_custom_verbose_option_name(invoke, args, assert_output_regex)

tests.test_logging.test_unrecognized_verbosity_level(invoke, cmd_decorator, cmd_type)

tests.test_logging.test_standalone_option_default_logger(invoke, cmd_decorator, option_decorator, args, expected_level, assert_output_regex)

Checks: - option affect log level - the default logger is root - the default logger message format - level names are colored - log level is propagated to all other loggers

tests.test_logging.test_default_logger_param(invoke, logger_param, params)

Passing a logger instance or name to the default_logger parameter works.

tests.test_logging.test_new_extra_logger_name_passing(invoke)

Test extra logger with custom format, passed to the option by its name.

tests.test_logging.test_new_extra_logger_object_passing(invoke)

Test extra logger with custom format, passed as an object to the option.

tests.test_logging.test_new_extra_logger_root_config(invoke)

Modify the root logger via new_extra_logger()

tests.test_logging.test_logger_propagation(invoke)

tests.test_parameters module

class tests.test_parameters.Custom

Bases: ParamType

A dummy custom type.

name: str = 'Custom'

the descriptive name of this type

convert(value, param, ctx)

Convert the value to the correct type. This is not called if the value is None (the missing value).

This must accept string values from the command line, as well as values that are already the correct type. It may also convert other compatible types.

The param and ctx arguments may be None in certain situations, such as when converting prompt input.

If the value cannot be converted, call fail() with a descriptive message.

Parameters:

• value – The value to convert.

• param – The parameter that is using this type to convert its value. May be None.

• ctx – The current context that arrived at this value. May be None.

tests.test_parameters.test_params_auto_types(invoke, option_decorator)

Check parameters types and structure are properly derived from CLI.

tests.test_parameters.assert_table_content(output, expected_table, table_format=None)

Helper to assert the content of a rendered table in the output.

Return type:

None

tests.test_parameters.test_standalone_show_params_option(invoke, cmd_decorator, option_decorator, assert_output_regex)

tests.test_parameters.test_integrated_show_params_option(invoke, create_config)

tests.test_parameters.test_recurse_subcommands(invoke)

tests.test_parameters.test_standalone_table_rendering(invoke, opt1, opt2, table_format)

Check all rendering styles of the table with standalone --show-params and --table-format option.

tests.test_parameters.test_standalone_no_color_rendering(invoke, opt1, opt2, opt3, table_format)

Check that all rendering styles are responding to the --color/--no-color option.

tests.test_pygments module

tests.test_pygments.test_ansi_lexers_candidates(tmp_path)

Look into Pygments test suite to find all ANSI lexers candidates.

Good candidates for ANSI colorization are lexers that are producing Generic.Output tokens, which are often used by REPL-like and scripting terminal to render text in a console.

The list is manually maintained in Click Extra code, and this test is here to detect new candidates from new releases of Pygments.

Attention

The Pygments source code is downloaded from GitHub in the form of an archive, and extracted in a temporary folder.

The version of Pygments used for this test is the one installed in the current environment.

Danger

Security check While extracting the archive, we double check we are not fed an archive exploiting relative .. or . path attacks.

tests.test_pygments.collect_classes(klass, prefix='Ansi')

Returns all classes defined in click_extra.pygments that are a subclass of klass, and whose name starts with the provided prefix.

tests.test_pygments.get_pyproject_section(*section_path)

Descends into the TOML tree of pyproject.toml to reach the value specified by section_path.

Return type:

dict[str, str]

tests.test_pygments.check_entry_points(entry_points, *section_path)

Return type:

None

tests.test_pygments.test_formatter_entry_points()

tests.test_pygments.test_filter_entry_points()

tests.test_pygments.test_lexer_entry_points()

tests.test_pygments.test_registered_formatters()

tests.test_pygments.test_registered_filters()

tests.test_pygments.test_registered_lexers()

tests.test_pygments.test_ansi_lexers_doc()

tests.test_pytest module

Test the Pytest helpers.

tests.test_pytest.test_aligned_colored_fixtures(uncolored, colored)

tests.test_sphinx module

Fixtures and utilities for Sphinx testing.

tests.test_sphinx.test_sphinx_extension_setup(sphinx_app)

Test that the Sphinx extension is properly loaded.

tests.test_sphinx_alerts module

Tests for GitHub alert syntax conversion in Sphinx with MyST parser.

tests.test_sphinx_alerts.test_all_alert_types(alert_type)

Test all supported alert types are converted correctly.

tests.test_sphinx_alerts.test_alert_conversion(text, expected)

Test GitHub alerts are converted to MyST admonitions.

When expected is None, no conversion should occur.

tests.test_sphinx_alerts.test_sphinx_integration(sphinx_app, test_case)

Integration-critical tests that verify Sphinx rendering behavior.

tests.test_sphinx_alerts.test_github_alert_no_colon_fence(tmp_path)

Test that ConfigError is raised when colon_fence is not enabled.

tests.test_sphinx_alerts.test_github_alert_in_included_files(sphinx_app_myst_with_include, included_files, main_content, expected_fragments, unexpected_fragments)

Test GitHub alerts in included files with various configurations.

tests.test_sphinx_click module

Tests for Sphinx directives click:source and click:run in rST and MyST formats.

tests.test_sphinx_click.test_directive_functionality(sphinx_app, test_case)

Test standard directive functionalities in both rST and MyST.

tests.test_sphinx_click.test_directive_option_format(sphinx_app_rst)

rST will fail to render if an :option: is not followed by an empty line.

tests.test_sphinx_click.test_directive_option_language_override(sphinx_app)

Test that language override works for click:run directive.

tests.test_sphinx_click.test_sphinx_directive_state_persistence(sphinx_app)

Test that state persists between declare and run directives in real Sphinx.

tests.test_sphinx_click.test_directive_variable_conflict(var_name, sphinx_app, content, directive_lineno, error_lineno)

Test that variable conflicts are properly detected in real Sphinx environment.

tests.test_sphinx_click.test_exit_exception_percolate(sphinx_app)

Test directives that handle command errors and exit codes.

tests.test_table module

tests.test_table.test_table_formats_definition()

Check all table formats are accounted for and properly named.

tests.test_table.test_unrecognized_format(invoke, cmd_decorator, cmd_type)

tests.test_table.test_all_table_formats_have_test_rendering()

Check all table formats have a rendering test fixture defined.

tests.test_table.test_all_table_rendering(invoke, cmd_decorator, option_decorator, format_name, expected)

tests.test_telemetry module

tests.test_telemetry.test_standalone_telemetry_option(invoke, cmd_decorator, telemetry_help, option_decorator)

tests.test_telemetry.test_multiple_envvars(invoke, cmd_decorator, telemetry_help)

tests.test_testing module

Test the testing utilities and the simulation of CLI execution.

tests.test_testing.test_real_fs()

Check a simple test is not caught into the CLI runner fixture which is encapsulating all filesystem access into temporary directory structure.

tests.test_testing.test_temporary_fs(extra_runner)

Check the CLI runner fixture properly encapsulated the filesystem in temporary directory.

tests.test_testing.test_runner_output()

tests.test_testing.check_default_colored_rendering(result)

tests.test_testing.check_default_uncolored_rendering(result)

tests.test_testing.check_forced_uncolored_rendering(result)

tests.test_testing.test_invoke_optional_color(invoke)

tests.test_testing.test_invoke_default_color(invoke)

tests.test_testing.test_invoke_forced_color_stripping(invoke)

tests.test_testing.test_invoke_color_keep(invoke)

tests.test_testing.test_invoke_color_forced(invoke)

Test colors are preserved while invoking, and forced to be rendered on Windows.

tests.test_timer module

Test defaults of our custom commands, as well as their customizations and attached options, and how they interact with each others.

tests.test_timer.test_integrated_time_option(invoke, subcommand_id, time_min)

tests.test_timer.test_integrated_notime_option(invoke, subcommand_id)

tests.test_timer.test_standalone_timer_option(invoke, cmd_decorator, option_decorator, assert_output_regex)

tests.test_types module

tests.test_types.test_click_choice_behavior()

Lockdown the behavior of method inherited from Click’s Choice type.

Return type:

None

tests.test_types.test_enum_string_choices(enum_definition, choice_source, result)

Return type:

None

tests.test_types.test_enum_choice_show_aliases(enum_definition, choice_source, show_aliases, result)

Test that EnumChoice correctly handles Enum with aliases.

Return type:

None

class tests.test_types.MyEnum(*values)

Bases: Enum

Produce different strings for keys/names, values and str().

FIRST_VALUE = 'first-value'

SECOND_VALUE = 'second-value'

tests.test_types.test_enum_choice_internals(source, expected_choices)

Return type:

None

tests.test_types.test_enum_choice_case_sensitivity(case_sensitive)

Return type:

None

tests.test_types.test_enum_choice_duplicate_string()

Return type:

None

tests.test_types.test_enum_choice_command(invoke, cmd_decorator, opt_decorator, case_sensitive, valid_args, invalid_args)

Test EnumChoice used within an option.

Return type:

None

tests.test_types.test_enum_choice_default_value(invoke, cmd_decorator, opt_decorator, opt_type, default_value)

Test EnumChoice used within an option with a default value.

Return type:

None

tests.test_version module

Test the --version option.

Todo

Test standalone scripts setting package name to filename and version to None.

Todo

Test standalone script fetching version from __version__ variable.

tests.test_version.test_standalone_version_option(invoke, cmd_decorator, option_decorator)

tests.test_version.test_debug_output(invoke, cmd_decorator, option_decorator, assert_output_regex)

tests.test_version.test_set_version(invoke)

tests.test_version.test_custom_message(invoke, cmd_decorator, message, regex_stdout, assert_output_regex)

tests.test_version.test_style_reset(invoke, cmd_decorator)

tests.test_version.test_custom_message_style(invoke, cmd_decorator)

tests.test_version.test_context_meta(invoke, cmd_decorator, assert_output_regex)

tests.test_version.test_integrated_version_option_precedence(invoke, params)

tests.test_version.test_color_option_precedence(invoke)

–no-color has an effect on –version, if placed in the right order.

Eager parameters are evaluated in the order as they were provided on the command line by the user as expleined in: https://click.palletsprojects.com/en/8.0.x/advanced/#callback-evaluation-order

Todo

Maybe have the possibility to tweak CLI callback evaluation order so we can let the user to have the NO_COLOR env set to allow for color-less --version output.