tests package

Submodules

tests.conftest module

Fixtures, configuration and helpers for tests.

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()

Verify click_extra.__all__ is a superset of click and cloup.

Sort order is enforced by ruff (RUF022).

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/click-concepts/#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, lazy_group_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_found(invoke, simple_config_cli, conf_path)

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

Explicit –config pointing to a file with garbage content.

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

Explicit –config pointing to an empty file.

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, conf_text, expect_error)

Strict mode rejects unknown params but accepts clean configs.

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_conf_metadata_no_config(invoke)

ctx.meta entries are not set when –no-config skips loading.

tests.test_config.test_default_map_populated(invoke, create_config)

Verify default_map structure when config values match CLI parameters.

Complements test_conf_metadata which only checks the empty default_map case (where no config values match the CLI’s parameter structure).

tests.test_config.test_default_map_none_without_config(invoke)

Verify default_map is left alone when –no-config is used.

tests.test_config.test_nested_subcommand_config(invoke, create_config)

Config propagates through group -> subgroup -> leaf command.

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_lazy_group_config(invoke, create_config, tmp_path)

Test that lazy groups work with config files.

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

tests.test_config.test_lazy_group_config_no_config_flag(invoke, create_config, tmp_path)

Test that –no-config works with lazy groups.

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, monkeypatch)

Test that roaming and force_posix affect the default pattern generation.

tests.test_config.test_default_pattern_xdg_config_home(force_posix, tmp_path, monkeypatch)

Test that default_pattern respects XDG_CONFIG_HOME on Linux.

tests.test_config.test_parent_patterns(tmp_path, search_parents, subdirs, create_file, expected_start)

tests.test_config.test_parent_patterns_with_magic_pattern(tmp_path, pattern_factory, expected_factory)

Test parent_patterns with glob patterns containing magic characters.

tests.test_config.test_parent_patterns_magic_no_search(tmp_path)

Magic pattern with search_parents=False yields only the original.

tests.test_config.test_parent_patterns_relative_path(tmp_path)

Test parent_patterns resolves relative paths to absolute.

tests.test_config.test_parent_patterns_stop_at_path(tmp_path)

stop_at as a path limits the parent directory walk.

tests.test_config.test_parent_patterns_stop_at_vcs(tmp_path, has_vcs, expected_bounded)

stop_at=VCS stops at VCS root, or walks to filesystem root if none.

tests.test_config.test_parent_patterns_inaccessible_directory(tmp_path)

Walk stops at an inaccessible directory.

tests.test_config.test_find_vcs_root(tmp_path, vcs_dir, expected)

Test _find_vcs_root with .git, .hg, and no VCS markers.

tests.test_config.test_config_option_default_no_config(invoke, create_config)

ConfigOption with default=NO_CONFIG disables autodiscovery.

tests.test_config.test_no_config_explicit_with_default_no_config(invoke)

–no-config still prints the skip message even when NO_CONFIG is the default.

tests.test_config.test_excluded_params(invoke, create_config)

Custom excluded_params prevents config values from being applied.

tests.test_config.test_included_params(invoke, create_config)

Only parameters in included_params are loaded from config.

tests.test_config.test_included_params_empty(invoke, create_config)

An empty included_params excludes all params from config.

tests.test_config.test_included_and_excluded_params_conflict()

Providing both included_params and excluded_params raises ValueError.

tests.test_config.test_multiple_files_matching_glob(invoke, create_config, tmp_path)

When multiple files match a glob, only the first parseable one is used.

tests.test_config.test_forced_flags_warnings(caplog)

Warnings fire when SPLIT, BRACE or NODIR flags are missing.

tests.test_config.test_brace_multi_format_search(invoke, tmp_path, ext)

All format extensions are found in the search directory.

Regression test: before BRACE expansion, only the first format in the default pattern got the directory prefix — others were searched in CWD.

tests.test_config.test_root_dir_parent_search_finds_non_toml(invoke, tmp_path)

Parent search with root_dir correctly finds non-TOML config in parents.

Before the root_dir refactoring, SPLIT patterns like *.toml|*.yaml only applied the directory prefix to the first sub-pattern. Now with root_dir, all sub-patterns are scoped to the correct directory.

tests.test_config.test_no_enabled_formats_raises()

ValueError raised when all formats are disabled.

tests.test_config.test_pyproject_toml_in_defaults()

ConfigOption() with default file_format_patterns includes PYPROJECT_TOML.

tests.test_config.test_pyproject_toml_tool_extraction(simple_config_cli)

parse_conf with PYPROJECT_TOML returns the [tool] subsection.

tests.test_config.test_pyproject_toml_no_tool_section(simple_config_cli)

pyproject.toml without [tool] returns empty dict.

tests.test_config.test_file_pattern_with_pyproject_toml()

Explicit file_format_patterns with PYPROJECT_TOML works.

tests.test_config.test_pyproject_toml_overrides_defaults(invoke, create_config)

End-to-end: a CLI with default formats reads from pyproject.toml.

tests.test_config.test_validate_config_valid(invoke, create_config)

–validate-config with a valid config file exits 0.

tests.test_config.test_validate_config_invalid_keys(invoke, create_config)

–validate-config with unrecognized keys exits 1.

tests.test_config.test_extensionless_config(invoke, create_config, default_pattern, expected_help_default)

Both broad and exact default patterns resolve the same .commandrc file.

The default parameter is printed as-is on the help screen, so an exact path is more informative than a broad glob, but both locate the same file.

tests.test_config.test_validate_config_unparsable(invoke, create_config)

–validate-config with garbage content exits 2.

tests.test_config.test_validate_config_missing_file(invoke, tmp_path)

–validate-config with a nonexistent file is caught by Click’s Path(exists=True).

tests.test_config.test_validate_config_requires_config_option(invoke, tmp_path)

–validate-config without @config_option raises RuntimeError.

tests.test_config.test_validate_config_pyproject_toml(invoke, create_config)

–validate-config works with pyproject.toml [tool.*] sections.

tests.test_config.test_default_subcommand_selection(invoke, create_config, cli_subcmd, expected, unexpected)

Config default is used when no subcommand given; CLI wins otherwise.

tests.test_config.test_default_subcommand_chained(invoke, create_config)

chain=True group runs multiple config-listed subcommands in order.

tests.test_config.test_default_subcommand_config_errors(invoke, create_config, conf_value, error_fragment)

Bad _default_subcommands values produce clear errors.

tests.test_config.test_default_subcommand_strict_mode_tolerance(invoke, create_config)

strict=True config with _default_subcommands doesn’t raise.

tests.test_config.test_default_subcommand_validate_config_tolerance(invoke, create_config)

–validate-config with _default_subcommands reports valid.

tests.test_config.test_default_subcommand_with_options(invoke, create_config)

Default subcommand receives its config-provided options.

tests.test_config.test_default_subcommand_no_config(invoke)

Normal behavior when no config file is loaded.

tests.test_config.test_default_subcommand_duplicates_warning(invoke, create_config)

Duplicate entries in _default_subcommands are deduplicated with a warning.

tests.test_config.test_default_subcommand_cli_override_debug_log(invoke, create_config)

Debug log emitted when CLI subcommands override config defaults.

tests.test_config.test_prepend_subcommand_selection(invoke, create_config, cli_subcmd, expected, unexpected)

Prepend fires regardless of whether a CLI subcommand is given.

tests.test_config.test_prepend_subcommand_with_defaults(invoke, create_config, cli_subcmd, expect_backup)

Prepend always applies; defaults only fire when no CLI subcommand given.

tests.test_config.test_prepend_subcommand_non_chained_error(invoke, create_config)

Error on non-chained group.

tests.test_config.test_prepend_subcommand_config_errors(invoke, create_config, conf_value, error_fragment)

Bad _prepend_subcommands values produce clear errors.

tests.test_config.test_prepend_subcommand_strict_mode_tolerance(invoke, create_config)

strict=True config with _prepend_subcommands doesn’t raise.

tests.test_config.test_prepend_subcommand_validate_config_tolerance(invoke, create_config)

–validate-config with _prepend_subcommands reports valid.

tests.test_config.test_prepend_subcommand_duplicates_warning(invoke, create_config)

Duplicate entries in _prepend_subcommands are deduplicated with a warning.

tests.test_config.test_prepend_subcommand_info_log(invoke, create_config)

INFO log emitted when _prepend_subcommands are injected.

tests.test_config.test_prepend_subcommand_multiple(invoke, create_config)

Multiple prepend subcommands run in order.

tests.test_config.test_sanity_broad_glob_narrow_format(caplog)

Broad glob + all-literal format patterns triggers a debug log.

tests.test_config.test_sanity_broad_glob_wildcard_format(caplog)

Broad glob + wildcard format patterns does NOT trigger the warning.

tests.test_config.test_sanity_disjoint_patterns(caplog)

Literal default not matching any format pattern triggers a debug log.

tests.test_config.test_sanity_disjoint_matching_literal(caplog)

Literal default matching a format pattern does NOT trigger the warning.

tests.test_config.test_sanity_format_extension_mismatch(caplog)

Format pattern extension mismatching its format triggers a debug log.

tests.test_config.test_sanity_format_extension_correct(caplog)

Correctly-matched format extension does NOT trigger the warning.

tests.test_config.test_sanity_dotfile_without_dotglob(caplog)

Dotfile in default without DOTGLOB triggers a debug log.

tests.test_config.test_sanity_dotfile_format_without_dotglob(caplog)

Dotfile in format patterns without DOTGLOB triggers a debug log.

tests.test_config.test_sanity_dotfile_with_dotglob(caplog)

Dotfile with DOTGLOB does NOT trigger the warning.

tests.test_config.test_sanity_no_explicit_default(caplog)

Without an explicit string default, checks 1/2/4 are skipped.

tests.test_config.test_sanity_format_mismatch_without_explicit_default(caplog)

Check 3 (format mismatch) runs even without explicit default.

tests.test_config.test_expand_dotted_keys(input_conf, expected)

tests.test_config.test_dotted_keys_in_config(invoke, simple_config_cli, create_config, conf_name, conf_text)

Dotted keys in config files are expanded into nested structures.

tests.test_config.test_expand_dotted_keys_conflict_warning(caplog, input_conf, warning_fragment)

Scalar/dict conflicts on the same key emit a warning.

tests.test_config.test_expand_dotted_keys_empty_segments(caplog, input_conf)

Dotted keys with empty segments are skipped with a warning.

tests.test_config.test_expand_dotted_keys_edge_cases(input_conf, expected)

tests.test_config.test_expand_dotted_keys_strict_conflict(input_conf, error_fragment)

Strict mode raises ValueError on type conflicts.

tests.test_config.test_expand_dotted_keys_strict_empty_segments(input_conf)

Strict mode raises ValueError on dotted keys with empty segments.

tests.test_config.test_strict_conf_dotted_key_conflict(invoke, create_config)

Strict mode rejects configs with dotted-key type conflicts.

tests.test_config.test_normalize_config_keys()

tests.test_config.test_config_schema_dataclass(invoke, create_config)

Dataclass schemas are auto-detected and instantiated with normalized keys.

tests.test_config.test_config_schema_callable(invoke, create_config)

A plain callable can be used as config_schema.

tests.test_config.test_config_schema_no_config_file(invoke)

When no config file is found, tool_config is not set.

tests.test_config.test_config_schema_dataclass_defaults(invoke, create_config)

Dataclass defaults are used for fields not present in the config file.

tests.test_config.test_fallback_sections(invoke, create_config)

Legacy section names are recognized with a deprecation warning.

tests.test_config.test_fallback_sections_prefers_current(invoke, create_config)

When both current and legacy sections exist, current wins.

tests.test_config.test_config_schema_multiple_formats(invoke, create_config, conf_name, conf_text)

Config schema works with YAML and JSON, not just TOML.

tests.test_config.test_config_schema_on_config_option_directly(invoke, create_config)

Config schema can be set directly on ConfigOption via the decorator.

tests.test_config.test_get_tool_config_defaults_to_current_context(invoke, create_config)

get_tool_config() works without passing ctx explicitly.

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_show_params_table_format_ordering(invoke, args_order)

--show-params respects --table-format regardless of CLI order.

tests.test_parameters.test_show_params_native_types(invoke, table_format)

Serialization formats emit native types instead of styled glyphs.

tests.test_parameters.test_recurse_subcommands(invoke)

tests.test_parameters.test_subcommand_conflicts_with_parent_param(invoke)

A subcommand whose name matches its direct parent’s param is a real conflict.

In a config file, the key would be ambiguous: is it the param value or the subcommand section?

[root.alpha]
# "foo" is ambiguous: is it the --foo param or the [root.alpha.foo] subcommand?
foo = ???

See: https://github.com/kdeldycke/click-extra/pull/1286

tests.test_parameters.test_nested_subcommand_no_false_conflict_with_root_param(invoke)

A nested subcommand can share a name with a root-level param without conflict.

The config paths are distinct (root.verbose vs root.alpha.verbose), so there is no ambiguity.

See: https://github.com/kdeldycke/click-extra/pull/1286

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.test_resolve_any_xref(sphinx_app)

Test that resolve_any_xref is implemented and returns an empty list.

See also

https://github.com/kdeldycke/click-extra/issues/1502

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_table.test_markup_strips_ansi_by_default(invoke, format_id)

Markup formats strip ANSI codes when --color is not forced.

tests.test_table.test_markup_preserves_ansi_with_color_flag(invoke, format_id)

--color overrides ANSI stripping for markup formats.

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_testing.test_extra_command_default_color()

With @command, ExtraContext defaults root color=True and ColorOption defaults True. Verify ctx.color=True and ANSI codes present in output.

tests.test_testing.test_extra_command_no_color_flag()

Invoke with –no-color. Verify ctx.color=False and ANSI stripped from echo output.

tests.test_testing.test_force_color_attribute()

ExtraCliRunner.force_color=True overrides color parameter.

tests.test_testing.test_no_color_envvar()

NO_COLOR=1 env var causes ctx.color=False via ColorOption.

tests.test_testing.test_force_color_envvar()

FORCE_COLOR=1 env var keeps ctx.color=True via ColorOption.

tests.test_testing.test_extra_context_root_defaults_color_true()

Root ExtraContext without color= arg defaults to color=True.

tests.test_testing.test_extra_context_inherits_from_parent()

Child ExtraContext inherits color from parent when not set.

tests.test_testing.test_extra_context_explicit_overrides_parent()

Child ExtraContext with explicit color overrides parent.

tests.test_testing.test_should_strip_ansi_non_tty()

In a test runner (non-TTY), should_strip_ansi behaves based on color arg.

tests.test_testing.test_resolve_color_default_no_context()

Outside any Click context, resolve_color_default returns None or passed value.

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_types.test_enum_choice_callback(invoke, cmd_decorator, opt_decorator, choice_source, cli_value)

Test that option callbacks receive properly converted Enum members.

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_context_meta_laziness(invoke, cmd_decorator)

Accessing a single field from ctx.meta must not evaluate unrelated fields.

Ensures that the _LazyVersionDict defers property evaluation: reading click_extra.version should not trigger expensive properties like env_info or git fields.

tests.test_version.test_module_version_parent_package_fallback(monkeypatch)

module_version falls back to parent package’s __version__.

Simulates the Nuitka use-case: a CLI whose module is myapp.__main__ (no __version__), with the parent package myapp providing it.

tests.test_version.test_cli_frame_fallback(monkeypatch)

cli_frame() falls back to the outermost frame when all frames are from the Click ecosystem.

tests.test_version.test_integrated_version_option_precedence(invoke, params)

tests.test_version.test_version_fields_forwarded_to_version_option(invoke)

version_fields on @command forwards to ExtraVersionOption.

tests.test_version.test_version_fields_forwarded_on_group(invoke)

version_fields works on @group too.

tests.test_version.test_version_fields_multiple(invoke)

Multiple fields can be overridden at once.

tests.test_version.test_version_fields_rejects_unknown(invoke)

Unknown field names raise TypeError.

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/stable/click-concepts/#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.

tests.test_version.test_dev_version_appends_git_hash(invoke, cmd_decorator)

A .dev version gets a +hash suffix appended (or not, if git is unavailable).

tests.test_version.test_prebaked_dev_version_not_double_suffixed(invoke, cmd_decorator)

A version with an existing + is returned as-is — no second hash appended.

tests.test_version.test_release_version_unchanged(invoke, cmd_decorator)

A non-dev version is never modified.

tests.test_version.init_file(tmp_path)

Helper that creates a temporary __init__.py with the given content.

tests.test_version.test_prebake_dev_version(init_file)

A .dev version gets +hash appended in the file.

tests.test_version.test_prebake_single_quotes(init_file)

Single-quoted __version__ is also handled.

tests.test_version.test_prebake_already_baked_skipped(init_file)

A version with existing + is left untouched.

tests.test_version.test_prebake_release_skipped(init_file)

A release version (no .dev) is not modified.

tests.test_version.test_prebake_no_version_in_file(init_file)

A file without __version__ returns None.

tests.test_version.test_prebake_missing_local_version_raises(init_file)

Calling without local_version raises TypeError.

tests.test_version.test_prebake_idempotent(init_file)

Running prebake twice does not double-suffix.

tests.test_version.test_prebake_preserves_surrounding_content(init_file)

Content around __version__ is not disturbed.