{"id":25776233,"url":"https://github.com/STAMP-project/pitest-descartes","last_synced_at":"2025-02-27T06:05:52.547Z","repository":{"id":15704202,"uuid":"78643409","full_name":"STAMP-project/pitest-descartes","owner":"STAMP-project","description":"Descartes supports developers to improve their test suites by reporting weak spots in covered code","archived":false,"fork":false,"pushed_at":"2025-02-16T14:45:55.000Z","size":2953,"stargazers_count":126,"open_issues_count":28,"forks_count":21,"subscribers_count":14,"default_branch":"master","last_synced_at":"2025-02-16T15:27:17.577Z","etag":null,"topics":["h2020","inria","java","mutation-analysis","mutation-testing","pitest"],"latest_commit_sha":null,"homepage":"https://hal.archives-ouvertes.fr/hal-01870976/document","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"lgpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/STAMP-project.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-01-11T13:50:53.000Z","updated_at":"2024-09-15T03:44:52.000Z","dependencies_parsed_at":"2024-04-21T12:26:47.579Z","dependency_job_id":"7e03db6b-375d-4d9a-8634-5a924fd4723c","html_url":"https://github.com/STAMP-project/pitest-descartes","commit_stats":null,"previous_names":[],"tags_count":17,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/STAMP-project%2Fpitest-descartes","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/STAMP-project%2Fpitest-descartes/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/STAMP-project%2Fpitest-descartes/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/STAMP-project%2Fpitest-descartes/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/STAMP-project","download_url":"https://codeload.github.com/STAMP-project/pitest-descartes/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":240987435,"owners_count":19889333,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["h2020","inria","java","mutation-analysis","mutation-testing","pitest"],"created_at":"2025-02-27T06:01:19.690Z","updated_at":"2025-02-27T06:05:52.536Z","avatar_url":"https://github.com/STAMP-project.png","language":"Java","funding_links":[],"categories":["测试"],"sub_categories":[],"readme":"# Descartes: A Mutation Engine for PIT\n\n![build-on-push](https://github.com/STAMP-project/pitest-descartes/workflows/build-on-push/badge.svg)\n[![Maven Central](https://maven-badges.herokuapp.com/maven-central/eu.stamp-project/descartes/badge.svg?style=flat)](https://maven-badges.herokuapp.com/maven-central/eu.stamp-project/descartes)\n\n## What is Descartes?\nDescartes evaluates the capability of your test suite to detect bugs using extreme mutation testing. It is able to find your worst tested methods.\n\nDescartes is a mutation engine plugin for [PIT](http://pitest.org) which implements extreme mutation operators as proposed in the paper [Will my tests tell me if I break this code?](http://dl.acm.org/citation.cfm?doid=2896941.2896944).  \n\n## Quick start with Maven\n\nTo use Descartes in a Maven project, add the following plugin configuration to your `pom.xml`:\n\n```xml\n\u003cplugin\u003e\n  \u003cgroupId\u003eorg.pitest\u003c/groupId\u003e\n  \u003cartifactId\u003epitest-maven\u003c/artifactId\u003e\n  \u003cversion\u003e1.7.0\u003c/version\u003e\n  \u003cconfiguration\u003e\n    \u003cmutationEngine\u003edescartes\u003c/mutationEngine\u003e\n  \u003c/configuration\u003e\n  \u003cdependencies\u003e\n    \u003cdependency\u003e\n      \u003cgroupId\u003eeu.stamp-project\u003c/groupId\u003e\n      \u003cartifactId\u003edescartes\u003c/artifactId\u003e\n      \u003cversion\u003e1.3.2\u003c/version\u003e\n    \u003c/dependency\u003e\n  \u003c/dependencies\u003e\n\u003c/plugin\u003e\n```\n\nThen, execute the regular mutation coverage goal in the root folder of the project under test:\n\n```\ncd my-project-under-test\nmvn clean package org.pitest:pitest-maven:mutationCoverage\n```\n\nAll options from PIT can be used. For more details check [the PIT documentation](https://pitest.org/quickstart/maven/). \n\nCheck [\"Running Descartes on your project\"](#running-descartes-on-your-project) for additional Descartes configuration options. \n\nFor Gradle support check [Using Gradle](#using-gradle). \n\nFor quick configuration snippets showing how to use other testing frameworks such as JUnit 5 or TestNG and how to change Descartes' behavior check [How to...](docs/how-to.md). \n\nIf you use a multi-module project take a look at [PitMP](https://github.com/STAMP-project/pitmp-maven-plugin).\n\n## Table of contents\n  - [How does Descartes work?](#how-does-descartes-work)\n  - [Descartes Output](#descartes-output)\n  - [Running Descartes on your project](#running-descartes-on-your-project)\n    - [Using Maven](#using-maven)\n        - [Specifying operators](#specifying-operators)\n        - [Configuring stop methods](#configuring-stop-methods)\n        - [Configuring reports](#configuring-reports)\n    - [Using Gradle](#using-gradle)\n    - [Running from the command line](#running-from-the-command-line)\n    - [Installing and building from source](#installing-and-building-from-source)\n  - [Releases](https://github.com/STAMP-project/pitest-descartes/releases)\n  - [More...](#more)\n\n## How does Descartes work?\n### Mutation testing\nMutation testing allows you to verify if your test suite can detect possible bugs.\nThe technique works by introducing small changes or faults into the original program. These modified versions are called **mutants**.\nA good test suite should be able to detect or *kill* a mutant. That is, at least one test case should fail when the test suite is executed with the mutant. \n[Read more](https://en.wikipedia.org/wiki/Mutation_testing).\nTraditional mutation testing works at the instruction level, e.g., replacing \"\u003e\" by \"\u003c=\", so the number of generated mutants is huge, as the time required to check the entire test suite.\nThat's why the authors of [Will my tests tell me if I break this code?](http://dl.acm.org/citation.cfm?doid=2896941.2896944) proposed an *Extreme Mutation* strategy, which works at the method level.\n\n### Extreme Mutation Testing\nIn Extreme Mutation testing, the whole logic of a method under test is eliminated.\nAll statements in a `void` method are removed. In other case, the body is replaced by a single return statement. \nThis approach generates fewer mutants. Code from the authors can be found in [their GitHub repository](https://github.com/cqse/test-analyzer).\n\nThe goal of Descartes is to bring an effective implementation of this kind of mutation operator into the world of PIT and check its performance in real world projects.\n\n### Mutation operators\nThe goal of *extreme mutation operators* is to replace the body of a method by one simple return instruction\nor just remove all instructions if is possible. Descartes supports the following mutation operators:\n\n#### `void` mutation operator\nThis operator accepts a `void` method and removes all the instructions on its body. For example, with the following class as input:\n\n```Java\nclass A {\n\n  int field = 3;\n\n  public void Method(int inc) {\n    field += 3;\n  }\n\n}\n```\nthe mutation operator will generate:\n\n```Java\nclass A {\n\n  int field = 3;\n\n  public void Method(int inc) { }\n\n}\n```\n\n#### `null` mutation operator\nThis operator accepts a method with a reference return type and replaces all instructions\nwith `return null`. For example, using the following class as input:\n```Java\nclass A {\n    public A clone() {\n        return new A();\n    }\n}\n```\nthis operator will generate:\n\n```Java\nclass A {\n    public A clone() {\n        return null;\n    }\n}\n```\n#### `empty` mutation operator\n\nThis is a special operator which targets methods that return arrays. It replaces the entire\nbody with a `return` statement that produces an empty array of the corresponding type.\nFor example, the following class:\n\n```Java\nclass A {\n  public int[] getRange(int count) {\n    int[] result = new int[count];\n    for(int i=0; i \u003c count; i++) {\n      result[i] = i;\n    }\n    return result;\n  }\n}\n```\nwill become:\n\n```Java\nclass A {\n  public int[] getRange(int count) {\n    return new int[0];\n  }\n}\n```\n\n#### Constant mutation operator\nThis operator accepts any method with primitive or `String` return type. It replaces the method body\nwith a single instruction returning a defined constant.\nFor example, if the integer constant `3` is specified, then for the following class:\n\n```Java\nclass A {\n    int field;\n\n    public int getAbsField() {\n        if(field \u003e= 0)\n            return field;\n        return -field;\n    }\n}\n```\nthis operator will generate:\n\n```Java\nclass A {\n    int field;\n\n    public int getAbsField() {\n        return 3;\n    }\n}\n```\n\n#### `new` mutation operator\n\n*New in version 1.2.6*\n\nThis operator accepts any method whose return type has a constructor with no parameters and belongs to a `java` package.\nIt replaces the code of the method by a single instruction returning a new instance.\n\nFor example:\n\n```Java\nclass A {\n    int field;\n    \n    public ArrayList range(int end) {\n        ArrayList l = new ArrayList();\n        for(int i = 0; i \u003c size; i++) {\n            A a = new A();\n            a.field = i;\n            l.add(a);\n        }\n        return l;\n    }\n}  \n```\n \nis transformed to:\n\n```Java\nclass A {\n    int field;\n    \n    public List range(int end) {\n        return new ArrayList();\n    }\n}  \n```\n\nThis operator handles the following special cases:\n\n| Return Type  | Replacement  |\n|--------------|--------------|\n| `Collection` | `ArrayList`  |\n| `Iterable`   | `ArrayList`  |\n| `List`       | `ArrayList`  |\n| `Queue`      | `LinkedList` |\n| `Set`        | `HashSet`    |\n| `Map`        | `HashMap`    |\n\nThis means that if a method returns an instance of `Collection` the code of the mutated method will be\n`return new ArrayList();`.\n\nThis operator is not enabled by default.\n\n#### `optional` mutation operator\n\n*New in version 1.2.6*\n\nThis operator accepts any method whose return type is `java.util.Optional`.\nIt replaces the code of the method by a single instruction returning an *empty* instance.\n\nFor example:\n\n```Java\nclass A {\n    int field;\n    \n    public Optional\u003cInteger\u003e getOptional() {\n        return Optional.of(field);\n    }\n}  \n```\n \nis transformed to:\n\n```Java\nclass A {\n    int field;\n    \n   public Optional\u003cInteger\u003e getOptional() {\n           return Optional.empty();\n   }\n}  \n```\n\nThis operator is not enabled by default.\n\n#### `argument` mutation operator\n\n*New in version 1.3*\n\nThis operator replaces the body of a method by returning the value of the first parameter that has the same type as the return type of the method.\n\nFor example:\n\n```Java\nclass A {\n    public int m(int x, int y) {\n        return x + 2 * y;\n    }\n}\n```\n\nis transformed to:\n\n```Java\nclass A {\n    public int m(int x) {\n        return x;\n    }\n}\n```\n\nThis operator is not enabled by default.\n\n#### `this` mutation operator\n*New in version 1.3*\n\nReplaces the body of a method by `return this;` if applicable. The goal of this operator is to perform better transformations targeting fluent APIs.\n\nFor example:\n\n```Java\nclass A {\n\n    int value = 0;\n    public A addOne() {\n        value += 1;\n        return this;\n    }\n}\n```\n\nis transformed to:\n\n```Java\nclass A {\n\n    int value = 0;\n    public A addOne() {\n        return this;\n    }\n}\n```\n\nThis operator is not enabled by default.\n\n### Stop Methods\n\nDescartes avoids some methods that are generally not interesting and may introduce false positives such as simple getters, simple setters, empty void methods or methods returning constant values, delegation patterns as well as deprecated and compiler generated methods. Those methods are automatically detected by inspecting their code.\nA complete list of examples can be found [here](src/test/java/eu/stamp_project/test/input/StopMethods.java).\nThe exclusion of stop methods can be configured. For more details see section: [\"Running Descartes on your project\"](#running-descartes-on-your-project).\n\n### Do not use `null` in methods annotated with `@NotNull`\n\n*New in version 1.2.6*\n\nDescartes will avoid using the `null` operators in methods annotated with `@NotNull`. This increases its compatibility with Kotlin sources. This feature can be configured. See [\"Running Descartes on your project\"](#running-descartes-on-your-project) for more details.\n\n### Skip methods using `@DoNotMutate`\n\n*New in version 1.3*\n\nDescartes skips all method that are annotated with *any* annotation whose name is `DoNotMutate`. \nFor example, in the following fragment of code, the method `m` will not be mutated.\n\n```Java\nclass A {\n    @DoNotMutate\n    public void m() {...}\n}\n```\n\nAll methods in a class annotated with `@DoNotMutate` will be avoided as well. For example, in the following fragment of code, the method `m` will not be mutated:\n\n```Java\n@DoNotMutate\nclass A {\n    public void m() {...}\n}\n```\n\nThe `DoNotMutate` annotation may specify which operators should be considered. For example:\n\n```Java\nclass A {\n    @DoNotMutate(operators = \"false\")\n    public boolean m() { return true; }\n}\n```\n\nwill instruct Descartes not to use the `false` mutation operator to mutate `m`.\n\nWhen specifying operators, a method annotation takes precedence over class annotations. That, is the `@DoNotMutate` of a method overrides the same annotation in the class For example:\n\n```Java\n@DoNotMutate(operators = \"true\")\nclass A {\n\n    public boolean n() { return false; }\n\n    @DoNotMutate(operators = \"false\")\n    public boolean m() { return true; }\n}\n```\n\nwill not mutate method `n` with `true`, as instructed in the class annotation. On the other hand, `m` will be mutated by `true` but not by `false`. \n\nDescartes includes a definition of `DoNotMutate`. However, when the tool inspects the annotations of a class or method  it matches only the simple name of the annotation class and ignores the package. So, any `DoNotMutate` annotation will be considered. In this way a project does not need to add Descartes as a dependency, it can declare its own `DoNotMutate` and use it.\n\nThis feature is also configurable. See [\"Running Descartes on your project\"](#running-descartes-on-your-project) for more details.\n\n\n## Descartes Output\n\nPIT reporting extensions work with Descartes and include `XML`, `CSV` and `HTML` formats. The `HTML` format is rather convenient since it also shows the line coverage.\nDescartes also provides three new reporting extensions:\n  - a general reporting extension supporting `JSON` files. It works also with **Gregor**, the default mutation engine for PIT. To use just set `JSON` as report format for PIT.\n  - a reporting extension designed for Descartes that generates a JSON file with information about pseudo and partially tested methods. To use just set `METHOD` as report format for PIT.\n  - Descartes can generate a human-readable report containing only the list of methods with testing issues by using the `ISSUES` format.\n \nExamples of these reporting extensions for [Apache Commons-CLI](https://github.com/apache/commons-cli/tree/b9ccc94008c78a59695f0c77ebe4ecf284370956) can be checked [here](docs/examples/commons-cli).\n\nFor more details on how to use and configure these reporting extensions please check section: [\"Running Descartes on your project\"](#running-descartes-on-your-project). For a more detailed description of the formats see [Output Formats](./docs/output-format.md).\n\n## Running Descartes on your project\n\nStable releases of Descartes are available from Maven Central.\nDescartes is a plugin for PIT, so they have to be used together.\nPIT integrates with majors test and build tools such as [Maven](https://maven.apache.org),\n[Ant](http://apache.ant.org) and [Gradle](https://gradle.org).\n\n\n### Using Maven\n\nThe minimum configuration to use Descartes in a Maven project is the following:\n\n```xml\n\u003cplugin\u003e\n  \u003cgroupId\u003eorg.pitest\u003c/groupId\u003e\n  \u003cartifactId\u003epitest-maven\u003c/artifactId\u003e\n  \u003cversion\u003e1.7.0\u003c/version\u003e\n  \u003cconfiguration\u003e\n    \u003cmutationEngine\u003edescartes\u003c/mutationEngine\u003e\n  \u003c/configuration\u003e\n  \u003cdependencies\u003e\n    \u003cdependency\u003e\n      \u003cgroupId\u003eeu.stamp-project\u003c/groupId\u003e\n      \u003cartifactId\u003edescartes\u003c/artifactId\u003e\n      \u003cversion\u003e1.3.2\u003c/version\u003e\n    \u003c/dependency\u003e\n  \u003c/dependencies\u003e\n\u003c/plugin\u003e\n```\n\n\nThis actually configures PIT for the project, adds Descartes as a dependency of PIT and sets Descartes as the mutation engine to use.\nLater, one need to run the mutation coverage goal provided by the PIT Maven plugin as follows:\n\n```\ncd my-project-under-test\nmvn clean package # ensures clean state\nmvn org.pitest:pitest-maven:mutationCoverage\n```\n##### Specifying operators\n\nThe operators must be specified in the `pom.xml` file. Each operator identifier should be added to the `mutators` element inside the `configuration` element. `void` and `null` operators are identified by `void` and `null` respectively.\nThe values for the constant mutation operator can be specified using the regular literal notation used in a Java program. For example `true`, `1`, `2L`, `3.0f`, `4.0`, `'a'`, `\"literal\"`, represent `boolean`, `int`, `long`, `float`, `double`, `char`, `string` constants.\nNegative values and binary, octal and hexadecimal bases for integer constants are supported as stated by the [language specification](https://docs.oracle.com/javase/specs/jls/se7/html/jls-3.html#jls-3.10).\nIn order to specify a `byte` or `short` value, a cast-like notation can be used: `(short) -1`, `(byte)0x1A`.\n\nThe following configuration:\n```xml\n\u003cmutators\u003e\n    \u003cmutator\u003evoid\u003c/mutator\u003e\n    \u003cmutator\u003e4\u003c/mutator\u003e\n    \u003cmutator\u003e\"some string\"\u003c/mutator\u003e\n    \u003cmutator\u003efalse\u003c/mutator\u003e\n\u003c/mutators\u003e\n```\nwill instruct the tool to use the `void` operator. The constant operator will replace the body of every method returning `int` with `return 4;` and will use `\"some string\"` and `false` for every `string` and `boolean` method.\n\nBy default, Descartes uses the following operators:\n\n```xml\n\u003cmutators\u003e\n  \u003cmutator\u003evoid\u003c/mutator\u003e\n  \u003cmutator\u003enull\u003c/mutator\u003e\n  \u003cmutator\u003etrue\u003c/mutator\u003e\n  \u003cmutator\u003efalse\u003c/mutator\u003e\n  \u003cmutator\u003eempty\u003c/mutator\u003e\n  \u003cmutator\u003e0\u003c/mutator\u003e\n  \u003cmutator\u003e1\u003c/mutator\u003e\n  \u003cmutator\u003e(byte)0\u003c/mutator\u003e\n  \u003cmutator\u003e(byte)1\u003c/mutator\u003e\n  \u003cmutator\u003e(short)0\u003c/mutator\u003e\n  \u003cmutator\u003e(short)1\u003c/mutator\u003e\n  \u003cmutator\u003e0L\u003c/mutator\u003e\n  \u003cmutator\u003e1L\u003c/mutator\u003e\n  \u003cmutator\u003e0.0\u003c/mutator\u003e\n  \u003cmutator\u003e1.0\u003c/mutator\u003e\n  \u003cmutator\u003e0.0f\u003c/mutator\u003e\n  \u003cmutator\u003e1.0f\u003c/mutator\u003e\n  \u003cmutator\u003e'\\40'\u003c/mutator\u003e\n  \u003cmutator\u003e'A'\u003c/mutator\u003e\n  \u003cmutator\u003e\"\"\u003c/mutator\u003e\n  \u003cmutator\u003e\"A\"\u003c/mutator\u003e\n\u003c/mutators\u003e\n```\n\nAll the goals defined by the `pitest-maven` plugin work with Descartes. For more information check the [Maven plugin's web page](http://pitest.org/quickstart/maven/).\n\n##### Configuring stop methods\n\nTo configure the stop methods under consideration Descartes provides a `STOP_METHODS` [feature](http://pitest.org/quickstart/advanced/#mutation-interceptor).\nThis feature is enabled by default. The parameter `exclude` can be used to prevent certain methods to be treated as stop methods and bring them back to the analysis. This parameter can take any of the following values:\n\n\n| `exclude`       | Method description                                                                     | Example                                                                                          |\n|-----------------|----------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------|\n| `empty`         | `void` methods with no instruction.                                                    | `public void m() {}`                                                                             |\n| `enum`          | Methods generated by the compiler to support enum types (`values` and `valueOf`).      |                                                                                                  |\n| `to_string`     | `toString` methods.                                                                    |                                                                                                  |\n| `hash_code`     | `hashCode` methods.                                                                    |                                                                                                  |\n| `deprecated`    | Methods annotated with `@Deprecated` or belonging to a class with the same annotation. | `@Deprecated public void m() {...}`                                                              |\n| `synthetic`     | Methods generated by the compiler.                                                     |                                                                                                  |\n| `getter`        | Simple getters.                                                                        | `public int getAge() { return this.age; }`                                                       |\n| `setter`        | Simple setters. Includes also fluent simple setters.                                   | `public void setX(int x) { this.x = x; }` and `public A setX(int x){ this.x = x; return this; }` |\n| `constant`      | Methods returning a literal constant.                                                  | `public double getPI() { return 3.14; }`                                                         |\n| `delegate`      | Methods implementing simple delegation.                                                | `public int sum(int[] a, int i, int j) {return this.adder(a, i, j); }`                           |\n| `clinit`        | Static class initializers.                                                             |                                                                                                  |\n| `return_this`   | Methods that only return `this`.                                                       | `public A m() { return this; }`                                                                  |\n| `return_param`  | Methods that only return the value of a real parameter                                 | `public int m(int x, int y) { return y; }`                                                       |\n| `kotlin_setter` | Setters generated for data classes in Kotlin (*New in version 2.1.6*)                  |                                                                                                  |\n\nSo, for example, if we don't want to exclude deprecated methods and mutate them the following snippet should be added under the `configuration` element:\n\n```xml\n\u003cfeatures\u003e\n  \u003cfeature\u003e\n  \u003c!-- This will allow descartes to mutate deprecated methods --\u003e\n    +STOP_METHODS(except[deprecated])\n  \u003c/feature\u003e\n\u003c/features\u003e\n```\n\nMore than one group can be excluded at the same time:\n\n```xml\n\u003cfeatures\u003e\n  \u003cfeature\u003e\n  \u003c!-- This will allow descartes to mutate toString and enum generated methods --\u003e\n    +STOP_METHODS(except[to_string] except[enum])\n  \u003c/feature\u003e\n\u003c/features\u003e\n```\n\nThe feature can be completely disabled:\n\n```xml\n\u003cfeatures\u003e\n  \u003cfeature\u003e\n  \u003c!--No method is considered as a stop method and therefore all of them will be mutated --\u003e\n    -STOP_METHODS()\n  \u003c/feature\u003e\n\u003c/features\u003e\n```\n\n##### Configuring reports\n\nAs said before, there are several reporting options provided by Descartes:\n- `JSON` for a general mutation testing report using that file format. It can be used with **Gregor**.\n- `METHODS` that produces a `methods.json` file with the list of all methods analyzed and categorized according to the mutation testing result.\n- `ISSUES` a human-readable report containing only the methods with testing issues.\n\nThey can be configured and combined as regular PIT report formats:\n\n```xml\n\u003cplugin\u003e\n  \u003cgroupId\u003eorg.pitest\u003c/groupId\u003e\n  \u003cartifactId\u003epitest-maven\u003c/artifactId\u003e\n  \u003cversion\u003e1.7.0\u003c/version\u003e\n  \u003cconfiguration\u003e\n    \u003coutputFormats\u003e\n      \u003cvalue\u003eJSON\u003c/value\u003e\n      \u003cvalue\u003eMETHODS\u003c/value\u003e\n      \u003cvalue\u003eISSUES\u003c/value\u003e\n    \u003c/outputFormats\u003e\n    \u003cmutationEngine\u003edescartes\u003c/mutationEngine\u003e\n  \u003c/configuration\u003e\n    \u003cdependencies\u003e\n    \u003cdependency\u003e\n      \u003cgroupId\u003eeu.stamp-project\u003c/groupId\u003e\n      \u003cartifactId\u003edescartes\u003c/artifactId\u003e\n      \u003cversion\u003e1.3.2\u003c/version\u003e\n    \u003c/dependency\u003e\n  \u003c/dependencies\u003e\n\u003c/plugin\u003e\n```\n#### Other filters\n\nFrom version *1.2.6* Descartes includes `AVOID_NULL` as a feature preventing the `null` operator to mutate a method marked with `@NotNull`.\nThe feature is active by default.\n\nIt can be removed by adding the following configuration:\n\n```xml\n\u003cfeatures\u003e\n  \u003cfeature\u003e\n    -AVOID_NULL()\n  \u003c/feature\u003e\n\u003c/features\u003e\n```\n\nFrom version *1.3* Descartes includes `DO_NOT_MUTATE` as a feature preventing the mutation of method and classes annotated with `@DoNotMutate`. \nThe feature is active by default.\n\nIt can be removed by adding the following configuration:\n\n```xml\n\u003cfeatures\u003e\n  \u003cfeature\u003e\n    -DO_NOT_MUTATE()\n  \u003c/feature\u003e\n\u003c/features\u003e\n```\n\nFrom version *1.3* Descartes includes `SKIP_SHORT` as a feature to skip methods shorter than a given number of lines.\nThe feature is not active by default. To activate add the following configuration:\n\n```xml\n\u003cfeatures\u003e\n  \u003cfeature\u003e\n    +SKIP_SHORT()\n  \u003c/feature\u003e\n\u003c/features\u003e\n```\n\nThe number of lines can be configured as follows:\n\n```\n+SKIP_SHORT(lines[3])\n```\n\nThe line threshold is equal to 5 by default.\n\n### Using Gradle\nFollow the [instructions](http://gradle-pitest-plugin.solidsoft.info/) to set up PIT for a project that uses [Gradle](https://gradle.org/).\nAdd Descartes as a dependency of the `pitest` task\n\n```\npitest 'eu.stamp-project:descartes:1.3.2'\n```\n\nthen specify `descartes` in the `mutationEngine` option inside the plugin configuration.\n\nAn example of the final configuration could be:\n```\nplugins {\n    id 'java'\n    id 'info.solidsoft.pitest' version '1.5.1'\n}\n\n// Other configurations\n\nrepositories {\n    mavenCentral()\n    mavenLocal()\n}\n\ndependencies {\n    testImplementation group: 'junit', name: 'junit', version: '4.13.1'\n    pitest 'eu.stamp-project:descartes:1.3.2'\n}\n\npitest {\n  mutationEngine = \"descartes\"\n  pitestVersion = \"1.7.0\"\n}\n```\nThe `pitestVersion` property has to be specified to avoid version issues with the default version shipped with the Gradle plugin.\nAt last, run the `pitest` task for the project under test:\n\n```\ngradle pitest\n```\n\n#### Specifying operators\n\nTo specify a custom selection of mutation operators, use the `operators` property in the `pitest` block as follows:\n\n```\nmutators = [ '1.2', 'true', 'optional', '\"a\"' ]\n```\n\nThis mutates methods returning `double` values with `1.2`, boolean methods with `true`, methods returning `Optional` and methods returning `String`.\n\nSee the Maven section for more details on the operator identifiers.\n\n#### Configuring stop methods\n\nAs explained in the Maven section, Descartes skips some methods that are usually of no interest like simple getters and setters. However, these methods can be reincorporated to the analysis using the `STOP_METHODS` feature. The following removes all stop methods but allows mutating simple setters:\n\n```\nfeatures = ['+STOP_METHODS(except[setter])']\n```\n\nTo allow all stop methods do:\n\n```\nfeatures = ['-STOP_METHODS()']\n```\n\n#### Configuring reports\n\nDescartes custom output formats can be configured as follows:\n\n```\noutputFormats = ['ISSUES', 'METHODS', 'JSON']\n```\n\n#### Other features\n\nDescartes includes `AVOID_NULL` and `DO_NOT_MUTATE` features as explained previously. These are active by default. To disable this features it is enough to add the following configuration to the `pitest` block:\n\n```\nfeatures = ['-AVOID_NULL()']\n```\n\n```\nfeatures = ['-DO_NOT_MUTATE()']\n```\n\n### Running from the command line\nDescartes can be used when invoking PIT from the command line. To do this, follow [the instructions](http://pitest.org/quickstart/commandline/) to run PIT, include Descartes in the classpath specification and add `--mutationEngine=descartes`.\n\n### Installing and building from source\n\nIn a terminal, clone the repository:\n```\ngit clone https://github.com/STAMP-project/pitest-descartes.git\n```\nswitch to the cloned folder:\n```\ncd  pitest-descartes\n```\ninstall Descartes using the regular [Apache Maven](https://maven.apache.org) commands:\n```\nmvn install\n```\nAfter installing the package, PIT should be able to find the Descartes mutation engine.\n\n\n## More...\n\n### Performance\n\nYou can check [here](docs/performance-comparison.md) a comparison between Descartes and Gregor, the default mutation engine for PITest, considering the number of mutants both engines created for the same projects, and the total execution time.\n\n### External Links\n\nArticles mentioning Descartes:\n\n* [A Comprehensive Study of Pseudo-tested Methods](https://hal.inria.fr/hal-01867423/file/main.pdf) (Empirical Software Engineering, [doi:10.1007/s10664-018-9653-2](https://doi.org/10.1007/s10664-018-9653-2))\n* [Descartes: a PITest engine to detect pseudo-tested methods - Tool Demonstration](https://hal.inria.fr/hal-01870976/file/main.pdf) (Proceedings of ASE, [doi:10.1145/3238147.3240474](https://doi.org/10.1145/3238147.3240474))\n* [Mutation testing with PIT and Descartes](http://massol.myxwiki.org/xwiki/bin/view/Blog/MutationTestingDescartes)\n* [Controlling Test Quality](http://massol.myxwiki.org/xwiki/bin/view/Blog/ControllingTestQuality)\n\n### License\nDescartes is published under LGPL-3.0 (see [LICENSE.md](LICENSE) for further details).\n\n### Contributing\n\nIssues, pull requests and other contributions are welcome.\n\n### Funding\n\nUntil December 2019 Descartes was partially funded by research project STAMP (European Commission - H2020)\n![STAMP - European Commission - H2020](docs/logo_readme_md.png)\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FSTAMP-project%2Fpitest-descartes","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FSTAMP-project%2Fpitest-descartes","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FSTAMP-project%2Fpitest-descartes/lists"}