Introduction

Python's unittest command-line runner lets you target one specific test method instead of executing the whole suite. The trick is to use the fully qualified dotted path to the module, test case class, and method.

Run One Test Method

Given a file named test_math.py:

1import unittest
2
3
4class TestMath(unittest.TestCase):
5    def test_addition(self):
6        self.assertEqual(1 + 1, 2)
7
8    def test_subtraction(self):
9        self.assertEqual(5 - 3, 2)

Run only test_addition like this:

python -m unittest test_math.TestMath.test_addition

That is the canonical command-line pattern.

The Dotted Path Structure

The path has three pieces:

• module name
• 'TestCase class name'
• test method name

So:

test_math.TestMath.test_addition

means:

• import module test_math
• find class TestMath
• run method test_addition

If the test lives inside a package, include the package path too.

python -m unittest tests.unit.test_math.TestMath.test_addition

Run a Whole TestCase Class

If you want all tests in one class but not the rest of the suite:

python -m unittest test_math.TestMath

This is useful when debugging one area of behavior without running unrelated tests.

Use Verbose Output While Debugging

For clearer output:

python -m unittest -v test_math.TestMath.test_addition

The -v flag prints more detail about what was run and whether it passed or failed.

Discovery and Import Rules Still Apply

The command works only if Python can import the test module. That means:

• the module path must be correct
• the current working directory or PYTHONPATH must make the package importable

If the runner says it cannot import the module, the problem is often path resolution rather than the test name itself.

A Useful Habit for Bigger Projects

When test packages are nested, it is often easiest to copy the dotted import path directly from the package layout. For example:

1project/
2  tests/
3    unit/
4      test_math.py

The command is typically:

python -m unittest tests.unit.test_math.TestMath.test_addition

Thinking in import paths rather than file paths avoids a lot of confusion.

You Can Also Use Discovery with -k in Newer Python

If you prefer pattern matching over a full dotted path, newer Python versions also support -k with unittest discovery:

python -m unittest -k addition

That is broader than naming one exact test method, but it can be handy when you want to run a small subset of tests matching a pattern.

Why This Is Better Than Editing the Test File

Some developers temporarily comment out other tests or rename them just to run one method. The command-line selector is much better because:

• it keeps the test file unchanged
• it is repeatable
• it works well in shell history and scripts

That makes debugging faster and less error-prone.

Common Pitfalls

The biggest pitfall is using a filesystem path instead of a dotted Python import path. unittest wants module notation, not a shell file path with slashes.

Another common issue is misspelling the test method name. The method must exist exactly as written, including the test_ prefix.

People also forget the current working directory matters for imports. A correct dotted path may still fail if the command is run from the wrong place.

Summary

• Run one unittest method with python -m unittest module.TestCase.test_method.
• Use the full dotted import path, not a slash-based file path.
• Add -v for more readable debugging output.
• You can also target a whole TestCase class instead of one method.
• If the command fails, check import paths and the current working directory first.