How to Use the Command 'infection' (with Examples)

The infection command is a powerful mutation testing framework for PHP. Mutation testing is a form of software testing where certain changes are made to the code to ensure that test cases can detect and handle these mutations, enhancing the effectiveness and coverage of your test suite. The objective is to evaluate the robustness of your existing tests and identify which components of your code may need additional testing. infection specifically aids developers in running mutation tests on PHP projects to achieve a better understanding and improvement of their code integrity.

Use Case 1: Analyze Code Using the Configuration File

Code:

infection

Motivation:

Running infection without any additional parameters enables you to quickly start mutation testing using a default or existing configuration file. This is the simplest way to kick off the process, ensuring you can begin analyzing code right away. It eliminates the complexity and overhead of specifying numerous parameters, making it the go-to command for developers who want to jump directly into mutation testing.

Explanation:

• The command infection runs the mutation testing process. If a configuration file already exists in your project, it uses the settings from this file to conduct tests.
• If no configuration file exists, it prompts the creation of one. This file helps in customizing various aspects of mutation testing according to project needs.

Example Output:

✓ Configuration file created: infection.json.dist
✓ Indexing code source files
✓ Running initial tests...
✓ Running mutations...

Time: 2min 37s
Mutations: 1100
Killed: 1050
Survived: 50
Errors: 0

Use Case 2: Use a Specific Number of Threads

Code:

infection --threads 4

Motivation:

Using multiple threads to run infection tests can dramatically decrease the time taken to complete the mutation testing process, especially for large projects. This is useful for developers who wish to maximize their computational resources to perform tests in parallel, reducing idle time and potentially speeding up the development lifecycle.

Explanation:

• --threads 4 specifies that the mutation testing should run using 4 threads. This parallelizes the testing process, allowing multiple mutations to be tested concurrently.

Example Output:

✓ Running mutation tests with 4 threads...

Time: 1min 10s
Mutations: 1100
Killed: 1050
Survived: 50
Errors: 0

Use Case 3: Specify a Minimum Mutation Score Indicator (MSI)

Code:

infection --min-msi 80

Motivation:

Setting a minimum Mutation Score Indicator ensures that your test suite meets a certain level of effectiveness before the code is deemed fit for production. This helps maintain high code quality standards and encourages developers to create comprehensive test cases that rigorously evaluate their code.

Explanation:

• --min-msi 80 indicates that the minimum acceptable MSI is 80%. MSI is a measure of the proportion of mutations detected by the test suite, with a higher score reflecting better test coverage.

Example Output:

✓ Minimum MSI requirement met: 85%

Use Case 4: Specify a Minimum Covered Code MSI

Code:

infection --min-covered-msi 75

Motivation:

Focusing on the MSI of covered code alone helps prioritize testing efforts towards covered lines, ensuring that these parts of the code are sufficiently examined. This option is particularly important for projects aiming for high test coverage on critical code paths.

Explanation:

• --min-covered-msi 75 sets a threshold of 75% as the minimum MSI for covered code. It specifically measures the effectiveness of tests on lines of code that are already covered by tests, guaranteeing that these lines meet or exceed the defined MSI.

Example Output:

✓ Minimum covered MSI requirement met: 78%

Use Case 5: Use a Specific Test Framework

Code:

infection --test-framework phpunit

Motivation:

In PHP development, various test frameworks like PHPUnit and PHPSpec are commonly used. By specifying the test framework that aligns with your project’s existing setup, you ensure compatibility and take advantage of the unique features provided by each framework.

Explanation:

• --test-framework phpunit selects PHPUnit as the testing framework to use during mutation testing. This ensures that the generated mutations are evaluated using PHPUnit’s methodologies and integrations.

Example Output:

✓ Running with PHPUnit framework

Time: 1min 34s
Mutations: 1100
Killed: 1095
Survived: 5
Errors: 0

Use Case 6: Only Mutate Lines of Code That Are Covered by Tests

Code:

infection --only-covered

Motivation:

Focusing mutation tests solely on code that is test-covered is an efficient approach, as it prevents wasting resources on untested areas. This strategy helps developers prioritize improvements in tested code before expanding coverage further.

Explanation:

• --only-covered specifies that only the lines of code already covered by tests should be mutated. This reduces unnecessary mutations on untested code paths, ensuring the focus remains on improving the quality of the tested segments.

Example Output:

✓ Running mutations on covered lines only...

Time: 1min 20s
Mutations: 880
Killed: 870
Survived: 10
Errors: 0

Use Case 7: Display the Mutation Code That Has Been Applied

Code:

infection --show-mutations

Motivation:

For developers who wish to gain insights into how their code is being manipulated, displaying the mutations applied can be highly informative. This allows for better understanding of potential weak spots within the code and guides the writing of more comprehensive tests.

Explanation:

• --show-mutations displays the actual mutations that were applied during the testing process. Such visibility is crucial for detailed debugging and improvement of test strategies.

Example Output:

✓ Mutation: Changed "==" to "!=" at line 45
✓ Mutation: Replaced "+" with "-" at line 78

Mutations: 2
Killed: 2
Survived: 0
Errors: 0

Use Case 8: Specify the Log Verbosity

Code:

infection --log-verbosity all

Motivation:

Adjusting log verbosity allows developers to control the amount of information outputted during tests. For comprehensive analysis or debugging, detailed logs are invaluable, while minimal logs may be preferred in production environments.

Explanation:

• --log-verbosity all sets the logging level to “all,” ensuring that detailed logs are generated for every part of the process. This includes detailed reports of mutations, test results, and potential issues encountered.

Example Output:

✓ Detailed log started...
✓ Mutation applied at line 23
✓ Test passed for mutation applied at line 45
✓ Detailed log ended.

Time: 2min 10s

Conclusion:

The infection command provides diverse and robust functionality for PHP developers looking to enhance their project’s test suite via mutation testing. By offering customizable parameters, such as the number of threads used, threshold levels for MSI, specific test frameworks, and others, developers can fine-tune their testing process to align with their project’s unique requirements. This not only boosts code quality and reliability but also strengthens the entire development workflow.