Introduction

In Python's unittest module, assertEqual is the standard equality assertion. assertEquals existed as an older alias, but it is deprecated, so modern code should use assertEqual and treat assertEquals as legacy syntax that may still appear in older test suites.

Use assertEqual in New Tests

The current, conventional method name is assertEqual:

1import unittest
2
3class MathTests(unittest.TestCase):
4    def test_sum(self):
5        self.assertEqual(2 + 3, 5)
6
7if __name__ == "__main__":
8    unittest.main()

This is the form you should write in new code and expect in maintained examples.

What assertEquals Really Is

Historically, assertEquals was just an alias. It was not a different kind of equality check and did not provide a special comparison rule.

That means these two calls were intended to express the same idea:

self.assertEqual(value, expected)
self.assertEquals(value, expected)

The reason the older alias fell out of favor is consistency. The unittest API generally uses singular names such as assertEqual, assertTrue, assertFalse, and assertIn, so assertEquals became an awkward exception.

Why the Deprecation Matters

Deprecation is useful here because it removes needless ambiguity. When a codebase mixes assertEqual and assertEquals, readers may waste time wondering whether the two names have different semantics when they usually do not.

Using the preferred name gives you:

• clearer consistency with the rest of unittest
• less noise in code review
• fewer legacy constructs in active test code

It is a small cleanup, but it improves readability across large suites.

Migrating Old Tests Is Usually Simple

If you inherit an older test suite, the migration is normally just a rename:

class LegacyTests(unittest.TestCase):
    def test_upper(self):
        self.assertEqual("abc".upper(), "ABC")

Because the intent stays the same, this is usually a low-risk refactor.

Readability Matters More Than the Alias

Good test code should make failure output easy to understand at a glance. Using the standard assertion name helps, but so does putting the actual value first and the expected value second consistently across the suite. Small consistency choices like that make large test suites easier to scan and maintain.

Legacy Cleanup Is Usually Mechanical

Because assertEquals is mainly a naming issue, replacing it with assertEqual is usually a style cleanup rather than a semantic rewrite. That makes it a good candidate for small maintenance passes that improve consistency without changing test intent.

Choose the Most Specific Assertion When Needed

The more important testing decision is often not the alias, but whether equality is the best assertion at all. For example:

• use assertIs for identity
• use assertAlmostEqual for floating-point tolerance
• use container-specific assertions when they better express intent

So while assertEquals versus assertEqual is mostly a naming question, it is still worth thinking about the broader assertion choice.

Common Pitfalls

• Thinking assertEquals and assertEqual perform different comparison logic. In normal unittest usage, they do not.
• Writing new tests with assertEquals just because it appears in legacy code.
• Leaving deprecated names in actively maintained tests when a simple cleanup would improve consistency.
• Using a generic equality assertion when a more specific assertion would communicate intent better.
• Confusing equality with identity and choosing the wrong assertion family entirely.

Summary

• 'assertEqual is the standard equality assertion in Python unittest.'
• 'assertEquals is an older alias and should be treated as legacy syntax.'
• New code should use assertEqual for consistency and clarity.
• Updating old tests is usually just a rename with no behavioral difference.
• The larger testing goal is to choose the clearest assertion for the behavior being verified.