mutmut 3.3.1__tar.gz → 3.5.0__tar.gz

{mutmut-3.3.1 → mutmut-3.5.0}/HISTORY.rst

@@ -1,6 +1,52 @@
 Changelog
 ---------
 
+3.5.0
+~~~~~
+
+* Filter mutants based on type annotations. This feature needs to be turned on with the `type_check_command` config.
+
+* Support running on Windows
+
+* Save mutation stats for use with CI/CD pipeline (#460)
+
+* Async functions fixed
+
+* Fix for functions with positional only arguments
+
+* Support signatures with PEP 649 deferred annotations
+
+
+3.4.0
+~~~~~
+
+* Add action to view tests for mutant
+
+* Add basic description for all results in mutmut browse
+
+* Add description for timeout mutants
+
+* Early exit when stats find no tests for any mutant
+
+* Support python 3.14
+
+* Performance improvements
+
+* Fix `mutate_only_covered_lines` when files are excluded from test run
+
+* Add `pytest_add_cli_args` and `pytest_add_cli_args_test_selection` configs
+
+* `mutate_only_covered_lines` added to config to control whether coverage.py is used to filter down mutations
+
+* Filter out identical string mutants with different values
+
+* Handle more exit codes
+
+* Disable common order-randomising pytest plugins, as that can seriously deteriorate mutation testing performance
+
+* Fixed packaging issue
+
+
 3.3.1
 ~~~~~
 
@@ -143,7 +189,7 @@ Changelog
 3.0.0
 ~~~~~
 
-* Execution model switched to mutation schemata, which enabled parallell execution.
+* Execution model switched to mutation schemata, which enabled parallel execution.
 
 * New terminal UI
 

{mutmut-3.3.1/mutmut.egg-info → mutmut-3.5.0}/PKG-INFO

@@ -1,26 +1,35 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.4
 Name: mutmut
-Version: 3.3.1
+Version: 3.5.0
 Summary: mutation testing for Python 3
-Home-page: https://github.com/boxed/mutmut
+Keywords: mutmut,mutant,mutation,test,testing
 Author: Anders Hovmöller
-Author-email: boxed@killingar.net
-License: BSD
-Keywords: mutmut mutant mutation test testing
+Author-email: Anders Hovmöller <boxed@killingar.net>
+License-Expression: BSD-3-Clause
+License-File: LICENSE
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
-Classifier: License :: OSI Approved :: BSD License
 Classifier: Natural Language :: English
 Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.7
-License-File: LICENSE
-License-File: AUTHORS.rst
-Requires-Dist: libcst~=1.7.0
-Requires-Dist: click
-Requires-Dist: setproctitle
-Requires-Dist: textual
-Requires-Dist: toml>=0.10.2; python_version < "3.11"
-Requires-Dist: pytest
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Dist: click>=8.0.0
+Requires-Dist: coverage>=7.3.0
+Requires-Dist: libcst>=1.8.5
+Requires-Dist: pytest>=6.2.5
+Requires-Dist: setproctitle>=1.1.0
+Requires-Dist: textual>=1.0.0
+Requires-Dist: toml>=0.10.2 ; python_full_version < '3.11'
+Requires-Python: >=3.10
+Project-URL: Changelog, https://github.com/boxed/mutmut/blob/main/HISTORY.rst
+Project-URL: Documentation, https://mutmut.readthedocs.io/en/latest/
+Project-URL: Homepage, https://github.com/boxed/mutmut
+Project-URL: Issues, https://github.com/boxed/mutmut/issues
+Project-URL: Repository, https://github.com/boxed/mutmut
+Description-Content-Type: text/x-rst
 
 mutmut - python mutation tester
 ===============================
@@ -91,6 +100,20 @@ source code control and committed before you apply a mutant!
 If during the installation you get an error for the `libcst` dependency mentioning the lack of a rust compiler on your system, it is because your architecture does not have a prebuilt binary for `libcst` and it requires both `rustc` and `cargo` from the [rust toolchain](https://www.rust-lang.org/tools/install) to be built. This is known for at least the `x86_64-darwin` architecture.
 
 
+Wildcards for testing mutants
+-----------------------------
+
+Unix filename pattern matching style on mutants is supported. Example:
+
+.. code-block:: console
+
+    mutmut run "my_module*"
+    mutmut run "my_module.my_function*"
+
+In the `browse` TUI you can press `f` to retest a function, and `m` to retest
+an entire module.
+
+
 Configuration
 -------------
 
@@ -100,7 +123,7 @@ In `setup.cfg` in the root of your project you can configure mutmut if you need
 
     [mutmut]
     paths_to_mutate=src/
-    tests_dir=tests/
+    pytest_add_cli_args_test_selection=tests/
 
 If you use `pyproject.toml`, you must specify the paths as array in a `tool.mutmut` section:
 
@@ -108,27 +131,13 @@ If you use `pyproject.toml`, you must specify the paths as array in a `tool.mutm
 
     [tool.mutmut]
     paths_to_mutate = [ "src/" ]
-    tests_dir = [ "tests/" ]
+    pytest_add_cli_args_test_selection= [ "tests/" ]
 
 See below for more options for configuring mutmut.
 
 
-Wildcards for testing mutants
------------------------------
-
-Unix filename pattern matching style on mutants is supported. Example:
-
-.. code-block:: console
-
-    mutmut run "my_module*"
-    mutmut run "my_module.my_function*"
-
-In the `browse` TUI you can press `f` to retest a function, and `m` to retest
-an entire module.
-
-
 "also copy" files
------------------
+~~~~~~~~~~~~~~~~~
 
 To run the full test suite some files are often needed above the tests and the
 source. You can configure to copy extra files that you need by adding
@@ -142,7 +151,7 @@ directories and files to `also_copy` in your `setup.cfg`:
 
 
 Limit stack depth
------------------
+~~~~~~~~~~~~~~~~~
 
 In big code bases some functions are called incidentally by huge swaths of the
 codebase, but you really don't want tests that hit those executions to count
@@ -166,7 +175,7 @@ caught.
 
 
 Exclude files from mutation
----------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 You can exclude files from mutation in `setup.cfg`:
 
@@ -176,8 +185,51 @@ You can exclude files from mutation in `setup.cfg`:
         *__tests.py
 
 
+Enable coverage.py filtering of lines to mutate
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+By default, mutmut will mutate only functions that are called. But, if you would like a finer grained (line-level)
+check for coverage, mutmut can use coverage.py to do that.
+
+If you only want to mutate lines that are called (according to coverage.py), you can set
+`mutate_only_covered_lines` to `true` in your configuration. The default value is `false`.
+
+
+.. code-block::
+
+    mutate_only_covered_lines=true
+
+
+Filter generated mutants with type checker
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+When your project is type checked using `mypy` or `pyrefly`, you can also use it to filter out invalid mutants.
+For instance, mutmut mutates `x: str = 'foo'` to `x: str = None` which can easily caught by type checkers.
+
+Using this filter can improve performance and reduce noise, however it can also hide a few relevant mutations:
+
+1. `x: str = None` may not be valid, but if your tests do not detect such a change it indicates that
+    the value of `x` is not properly tested (even if your type checker would catch this particular modification)
+2. In some edge cases with class properties (usually in the `__init__` method), the way `mypy` and `pyrefly` infer types does not work well
+    with the way mutmut mutates code. Some valid mutations like changing `self.x = 123` to `self.x = None` can
+    be filtered out, even though the may be valid.
+
+To enable this filtering, configure the `type_check_command` to output json results as follows:
+
+.. code-block::
+
+    # for pyrefly
+    type_check_command = ['pyrefly', 'check', '--output-format=json']
+    # for mypy
+    type_check_command = ['mypy', 'traces_parser', '--output', 'json']
+
+Currently, only `pyrefly` and `mypy` are supported.
+With `pyright` and `ty`, mutating a class method `Foo.bar()` can break the types of all methods of `Foo`,
+and therefore mutmut cannot match the type error with the mutant that caused the type error.
+
+
 Enable debug output (increase verbosity)
-----------------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 By default, mutmut "swallows" all the test output etc. so that you get a nice clean output.
 
@@ -191,7 +243,7 @@ to failing tests.
 
 
 Whitelisting
-------------
+~~~~~~~~~~~~
 
 You can mark lines like this:
 
@@ -207,6 +259,27 @@ whitelist lines are:
   to continue, but it's slower.
 
 
+Modifying pytest arguments
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You can add and override pytest arguments:
+
+.. code-block:: python
+
+    # for CLI args that select or deselect tests, use `pytest_add_cli_args_test_selection`
+    pytest_add_cli_args_test_selection = ["-m", "not fail", "-k", "test_include"]
+
+    # for other CLI args, use `pytest_add_cli_args`
+    pytest_add_cli_args = ["-p", "no:some_plugin"] # disable a plugin
+    pytest_add_cli_args = ["-o", "xfail_strict=False"] # overrides xfail_strict from your normal config
+
+    # if you want to ignore the normal pytest configuration
+    # you can specify a diferent pytest ini file to be used
+    pytest_add_cli_args = ["-c", "mutmut_pytest.ini"]
+    also_copy = ["mutmut_pytest.ini"]
+
+
+
 Example mutations
 -----------------
 

mutmut-3.3.1/PKG-INFO → mutmut-3.5.0/README.rst

@@ -1,27 +1,3 @@
-Metadata-Version: 2.1
-Name: mutmut
-Version: 3.3.1
-Summary: mutation testing for Python 3
-Home-page: https://github.com/boxed/mutmut
-Author: Anders Hovmöller
-Author-email: boxed@killingar.net
-License: BSD
-Keywords: mutmut mutant mutation test testing
-Classifier: Development Status :: 4 - Beta
-Classifier: Intended Audience :: Developers
-Classifier: License :: OSI Approved :: BSD License
-Classifier: Natural Language :: English
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.7
-License-File: LICENSE
-License-File: AUTHORS.rst
-Requires-Dist: libcst~=1.7.0
-Requires-Dist: click
-Requires-Dist: setproctitle
-Requires-Dist: textual
-Requires-Dist: toml>=0.10.2; python_version < "3.11"
-Requires-Dist: pytest
-
 mutmut - python mutation tester
 ===============================
 
@@ -91,6 +67,20 @@ source code control and committed before you apply a mutant!
 If during the installation you get an error for the `libcst` dependency mentioning the lack of a rust compiler on your system, it is because your architecture does not have a prebuilt binary for `libcst` and it requires both `rustc` and `cargo` from the [rust toolchain](https://www.rust-lang.org/tools/install) to be built. This is known for at least the `x86_64-darwin` architecture.
 
 
+Wildcards for testing mutants
+-----------------------------
+
+Unix filename pattern matching style on mutants is supported. Example:
+
+.. code-block:: console
+
+    mutmut run "my_module*"
+    mutmut run "my_module.my_function*"
+
+In the `browse` TUI you can press `f` to retest a function, and `m` to retest
+an entire module.
+
+
 Configuration
 -------------
 
@@ -100,7 +90,7 @@ In `setup.cfg` in the root of your project you can configure mutmut if you need
 
     [mutmut]
     paths_to_mutate=src/
-    tests_dir=tests/
+    pytest_add_cli_args_test_selection=tests/
 
 If you use `pyproject.toml`, you must specify the paths as array in a `tool.mutmut` section:
 
@@ -108,27 +98,13 @@ If you use `pyproject.toml`, you must specify the paths as array in a `tool.mutm
 
     [tool.mutmut]
     paths_to_mutate = [ "src/" ]
-    tests_dir = [ "tests/" ]
+    pytest_add_cli_args_test_selection= [ "tests/" ]
 
 See below for more options for configuring mutmut.
 
 
-Wildcards for testing mutants
------------------------------
-
-Unix filename pattern matching style on mutants is supported. Example:
-
-.. code-block:: console
-
-    mutmut run "my_module*"
-    mutmut run "my_module.my_function*"
-
-In the `browse` TUI you can press `f` to retest a function, and `m` to retest
-an entire module.
-
-
 "also copy" files
------------------
+~~~~~~~~~~~~~~~~~
 
 To run the full test suite some files are often needed above the tests and the
 source. You can configure to copy extra files that you need by adding
@@ -142,7 +118,7 @@ directories and files to `also_copy` in your `setup.cfg`:
 
 
 Limit stack depth
------------------
+~~~~~~~~~~~~~~~~~
 
 In big code bases some functions are called incidentally by huge swaths of the
 codebase, but you really don't want tests that hit those executions to count
@@ -166,7 +142,7 @@ caught.
 
 
 Exclude files from mutation
----------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 You can exclude files from mutation in `setup.cfg`:
 
@@ -176,8 +152,51 @@ You can exclude files from mutation in `setup.cfg`:
         *__tests.py
 
 
+Enable coverage.py filtering of lines to mutate
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+By default, mutmut will mutate only functions that are called. But, if you would like a finer grained (line-level)
+check for coverage, mutmut can use coverage.py to do that.
+
+If you only want to mutate lines that are called (according to coverage.py), you can set
+`mutate_only_covered_lines` to `true` in your configuration. The default value is `false`.
+
+
+.. code-block::
+
+    mutate_only_covered_lines=true
+
+
+Filter generated mutants with type checker
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+When your project is type checked using `mypy` or `pyrefly`, you can also use it to filter out invalid mutants.
+For instance, mutmut mutates `x: str = 'foo'` to `x: str = None` which can easily caught by type checkers.
+
+Using this filter can improve performance and reduce noise, however it can also hide a few relevant mutations:
+
+1. `x: str = None` may not be valid, but if your tests do not detect such a change it indicates that
+    the value of `x` is not properly tested (even if your type checker would catch this particular modification)
+2. In some edge cases with class properties (usually in the `__init__` method), the way `mypy` and `pyrefly` infer types does not work well
+    with the way mutmut mutates code. Some valid mutations like changing `self.x = 123` to `self.x = None` can
+    be filtered out, even though the may be valid.
+
+To enable this filtering, configure the `type_check_command` to output json results as follows:
+
+.. code-block::
+
+    # for pyrefly
+    type_check_command = ['pyrefly', 'check', '--output-format=json']
+    # for mypy
+    type_check_command = ['mypy', 'traces_parser', '--output', 'json']
+
+Currently, only `pyrefly` and `mypy` are supported.
+With `pyright` and `ty`, mutating a class method `Foo.bar()` can break the types of all methods of `Foo`,
+and therefore mutmut cannot match the type error with the mutant that caused the type error.
+
+
 Enable debug output (increase verbosity)
-----------------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 By default, mutmut "swallows" all the test output etc. so that you get a nice clean output.
 
@@ -191,7 +210,7 @@ to failing tests.
 
 
 Whitelisting
-------------
+~~~~~~~~~~~~
 
 You can mark lines like this:
 
@@ -207,6 +226,27 @@ whitelist lines are:
   to continue, but it's slower.
 
 
+Modifying pytest arguments
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You can add and override pytest arguments:
+
+.. code-block:: python
+
+    # for CLI args that select or deselect tests, use `pytest_add_cli_args_test_selection`
+    pytest_add_cli_args_test_selection = ["-m", "not fail", "-k", "test_include"]
+
+    # for other CLI args, use `pytest_add_cli_args`
+    pytest_add_cli_args = ["-p", "no:some_plugin"] # disable a plugin
+    pytest_add_cli_args = ["-o", "xfail_strict=False"] # overrides xfail_strict from your normal config
+
+    # if you want to ignore the normal pytest configuration
+    # you can specify a diferent pytest ini file to be used
+    pytest_add_cli_args = ["-c", "mutmut_pytest.ini"]
+    also_copy = ["mutmut_pytest.ini"]
+
+
+
 Example mutations
 -----------------
 

mutmut-3.5.0/pyproject.toml

@@ -0,0 +1,69 @@
+[project]
+name = "mutmut"
+version = "3.5.0"
+description = "mutation testing for Python 3"
+keywords = ["mutmut", "mutant", "mutation", "test", "testing"]
+authors = [
+    { name = "Anders Hovmöller", email = "boxed@killingar.net" },
+]
+requires-python = ">=3.10"
+readme = "README.rst"
+license = "BSD-3-Clause"
+license-files = ["LICENSE"]
+
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Natural Language :: English",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+]
+
+dependencies = [
+    "click>=8.0.0",
+    "coverage>=7.3.0",
+    "libcst>=1.8.5",
+    "pytest>=6.2.5",
+    "setproctitle>=1.1.0",
+    "textual>=1.0.0",
+    "toml>=0.10.2 ; python_full_version < '3.11'",
+]
+
+[project.urls]
+Homepage = "https://github.com/boxed/mutmut"
+Documentation = "https://mutmut.readthedocs.io/en/latest/"
+Repository = "https://github.com/boxed/mutmut"
+Issues = "https://github.com/boxed/mutmut/issues"
+Changelog = "https://github.com/boxed/mutmut/blob/main/HISTORY.rst"
+
+
+[project.scripts]
+mutmut = "mutmut.__main__:cli"
+
+[build-system]
+requires = ["uv_build>=0.9.5,<0.10.0"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+source-include = ["HISTORY.rst"]
+
+[dependency-groups]
+dev = [
+    "inline-snapshot>=0.32.0",
+    "pyrefly>=0.53.0",
+    "pytest-asyncio>=1.0.0",
+    "ruff>=0.15.1",
+]
+
+[tool.pytest.ini_options]
+testpaths = [
+    "tests",
+]
+asyncio_default_fixture_loop_scope = "function"
+
+[tool.inline-snapshot]
+format-command="ruff format --stdin-filename {filename}"

{mutmut-3.3.1 → mutmut-3.5.0/src}/mutmut/__init__.py

@@ -1,21 +1,24 @@
+import importlib.metadata
 from collections import defaultdict
 
-__version__ = '3.3.1'
+__version__ = importlib.metadata.version("mutmut")
 
 
-duration_by_test = {}
+duration_by_test = defaultdict(float)
 stats_time = None
 config = None
 
 _stats = set()
 tests_by_mangled_function_name = defaultdict(set)
-
+_covered_lines = None
 
 def _reset_globals():
     global duration_by_test, stats_time, config, _stats, tests_by_mangled_function_name
+    global _covered_lines
 
-    duration_by_test = {}
+    duration_by_test.clear()
     stats_time = None
     config = None
     _stats = set()
     tests_by_mangled_function_name = defaultdict(set)
+    _covered_lines = None