Test code created with unittest can be executed not only directly as a Python script (writing if __name__ == "__main__":), but also more flexibly using the python -m unittest command from the command line.
Using this command allows you to automatically find and run all test files in a directory at once, or to run only specific test methods. This article explains the basic usage of the python -m unittest command and how to specify the target for execution.
1. Automatic Discovery and Batch Execution (Test Discovery)
The most convenient feature is “Test Discovery.” Simply executing the following command in the project’s root directory will automatically find and run all test files located underneath it.
python -m unittest
Rules for Auto-Discovery
For this command to recognize a file as a test file, the following conditions must be met:
- The filename must start with
test(e.g.,test_calc.py,test_api.py). - It must be importable from the top-level directory (e.g., if it is part of a package).
If you name your files according to these rules, you can run all tests with a single command, even as the number of test files increases.
2. Specifying and Running a Specific Test File
If you want to test only a specific file, pass the file path (or module name) as an argument.
Specifying by File Path:
# For Windows
python -m unittest tests\test_calculations.py
# For macOS / Linux
python -m unittest tests/test_calculations.py
Specifying by Module Name: If the file is in a location recognized as a Python module, you can specify it using dot notation. The .py extension is not required.
python -m unittest tests.test_calculations
3. Specifying and Running Specific Classes or Methods
It is also possible to run only a specific test class or even a specific test method (function) within it. This is very useful when you want to repeatedly run only a specific test during debugging.
Syntax: python -m unittest module_name.ClassName.method_name
Example: Running only the test_add method of the TestCalc class inside the test_calculations.py file.
python -m unittest tests.test_calculations.TestCalc.test_add
Displaying Detailed Results (-v option)
If you want to know exactly which tests were executed and which succeeded or failed, add the -v (verbose) option.
python -m unittest -v
Example Execution Result:
test_add (tests.test_calculations.TestCalc) ... ok
test_divide (tests.test_calculations.TestCalc) ... ok
test_multiply (tests.test_calculations.TestCalc) ... FAIL
======================================================================
FAIL: test_multiply (tests.test_calculations.TestCalc)
...
The test method name and its result (ok, FAIL, ERROR) are displayed line by line, making it easier to grasp the situation.
Summary
You can streamline test execution using the python -m unittest command.
python -m unittest: Automatically finds and runs alltest*.pyfiles under the current directory.python -m unittest path: Runs a specific file.python -m unittest module.Class.method: Runs only a specific test case.-voption: Displays detailed execution results.
It is recommended to use them according to the situation, such as running only specific methods during development and running all tests before committing.
