Create `unittest` assertRaises conventions for exception groups

[gpshead]

Feature or enhancement

Proposal:

unittest.TestCase has a variety of assertRaises flavor APIs. We need to better explain how to practically use these with exception groups and the ExceptionGroup type. Possibly add additional APIs to make them easier.

This is a tracking issue for the linked discussion in case people have PRs to propose.

Has this already been discussed elsewhere?

I have already discussed this feature proposal on Discourse

Links to previous discussion of this feature:

https://discuss.python.org/t/improve-support-for-exception-groups-in-unittest/100803

[serhiy-storchaka]

What is a variety of assertRaises flavor APIs? There are only assertRaises and assertRaisesRegex.

[sobolevn]

It would be nice to have an API in the stdlib to test ExceptionGroup objects that are also a part of the stdlib.

@gpshead are you already working on this? I would love to give this a try with presenting a design spec / draft API, if you haven't started yet :) It would make the discussion easier.

[gpshead]

I am not working on this. I just filed the issue because it seems like a good idea.

…

On Sun, Aug 3, 2025, 11:39 AM sobolevn ***@***.***> wrote: *sobolevn* left a comment (python/cpython#137311) <#137311 (comment)> It would be nice to have an API in the stdlib to test ExceptionGroup objects that are also a part of the stdlib. @gpshead <https://github.com/gpshead> are you already working on this? I would love to give this a try with presenting a design spec / draft API, if you haven't started yet :) It would make the discussion easier. — Reply to this email directly, view it on GitHub <#137311 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAAQXC5F6VUJY4JVRCJNRPT3LZJP5AVCNFSM6AAAAACC5MTJ46VHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZTCNBYGYZDGNRZGA> . You are receiving this because you were mentioned.Message ID: ***@***.***>

[gpshead]

What is a variety of assertRaises flavor APIs? There are only assertRaises and assertRaisesRegex

"variety of" was just my vague choice of words for "more than one". I suppose it's really just two or four, depending on if you count context manager form as its own API or not. But it doesn't matter. :)

[oliversheridanmethven]

An mentioned in the original/linked thread, PyTest has some tools specific for ExceptionGroup: https://docs.pytest.org/en/stable/how-to/assert.html#assert-matching-exception-groups

That's not to say that the PyTest team have the right or wrong API for working with exception groups, but just to highlight that it is in their library and not in unittest's.

Long term the tools will no doubt arise in unittest (hopefully not too long), but I think in the short term it is very unclear in the documentation what the advised way of working with exception groups in as-of today.