Test: @test_throws add 3-arg form for testing exception type and message (#59117)

Author: IanButterworth

NEWS.md

@@ -81,6 +81,7 @@ Standard library changes
 
 * Test failures when using the `@test` macro now show evaluated arguments for all function calls ([#57825], [#57839]).
 * Transparent test sets (`@testset let`) now show context when tests error ([#58727]).
+* `@test_throws` now supports a three-argument form `@test_throws ExceptionType pattern expr` to test both exception type and message pattern in one call ([#59117]).
 
 #### InteractiveUtils
 

stdlib/Test/src/Test.jl

@@ -799,17 +799,29 @@ end
 
 """
     @test_throws exception expr
+    @test_throws extype pattern expr
 
 Tests that the expression `expr` throws `exception`.
 The exception may specify either a type,
 a string, regular expression, or list of strings occurring in the displayed error message,
 a matching function,
 or a value (which will be tested for equality by comparing fields).
+
+In the two-argument form, `@test_throws exception expr`, the `exception` can be a type or a pattern.
+
+In the three-argument form, `@test_throws extype pattern expr`, both the exception type and
+a message pattern are tested. The `extype` must be a type, and `pattern` may be
+a string, regular expression, or list of strings occurring in the displayed error message,
+a matching function, or a value.
+
 Note that `@test_throws` does not support a trailing keyword form.
 
 !!! compat "Julia 1.8"
     The ability to specify anything other than a type or a value as `exception` requires Julia v1.8 or later.
 
+!!! compat "Julia 1.13"
+    The three-argument form `@test_throws extype pattern expr` requires Julia v1.12 or later.
+
 # Examples
 ```jldoctest
 julia> @test_throws BoundsError [1, 2, 3][4]
@@ -823,13 +835,19 @@ Test Passed
 julia> @test_throws "Try sqrt(Complex" sqrt(-1)
 Test Passed
      Message: "DomainError with -1.0:\\nsqrt was called with a negative real argument but will only return a complex result if called with a complex argument. Try sqrt(Complex(x))."
+
+julia> @test_throws ErrorException "error foo" error("error foo 1")
+Test Passed
+      Thrown: ErrorException
 ```
 
-In the final example, instead of matching a single string it could alternatively have been performed with:
+In the third example, instead of matching a single string it could alternatively have been performed with:
 
 - `["Try", "Complex"]` (a list of strings)
 - `r"Try sqrt\\([Cc]omplex"` (a regular expression)
 - `str -> occursin("complex", str)` (a matching function)
+
+In the final example, both the exception type (`ErrorException`) and message pattern (`"error foo"`) are tested.
 """
 macro test_throws(extype, ex)
     orig_ex = Expr(:inert, ex)
@@ -847,6 +865,22 @@ macro test_throws(extype, ex)
     return :(do_test_throws($result, $orig_ex, $(esc(extype))))
 end
 
+macro test_throws(extype, pattern, ex)
+    orig_ex = Expr(:inert, ex)
+    ex = Expr(:block, __source__, esc(ex))
+    result = quote
+        try
+            Returned($ex, nothing, $(QuoteNode(__source__)))
+        catch _e
+            if $(esc(extype)) != InterruptException && _e isa InterruptException
+                rethrow()
+            end
+            Threw(_e, Base.current_exceptions(), $(QuoteNode(__source__)))
+        end
+    end
+    return :(do_test_throws($result, $orig_ex, $(esc(extype)), $(esc(pattern))))
+end
+
 const MACROEXPAND_LIKE = Symbol.(("@macroexpand", "@macroexpand1", "macroexpand"))
 
 function isequalexception(@nospecialize(a), @nospecialize(b))
@@ -864,49 +898,78 @@ end
 
 # An internal function, called by the code generated by @test_throws
 # to evaluate and catch the thrown exception - if it exists
-function do_test_throws(result::ExecutionResult, @nospecialize(orig_expr), extype)
+function do_test_throws(result::ExecutionResult, @nospecialize(orig_expr), extype, pattern=nothing)
     if isa(result, Threw)
         # Check that the right type of exception was thrown
         success = false
         message_only = false
         exc = result.exception
-        # NB: Throwing LoadError from macroexpands is deprecated, but in order to limit
-        # the breakage in package tests we add extra logic here.
-        from_macroexpand =
-            orig_expr isa Expr &&
-            orig_expr.head in (:call, :macrocall) &&
-            orig_expr.args[1] in MACROEXPAND_LIKE
-        if isa(extype, Type)
-            success =
-                if from_macroexpand && extype == LoadError && exc isa Exception
-                    Base.depwarn("macroexpand no longer throws a LoadError so `@test_throws LoadError ...` is deprecated and passed without checking the error type!", :do_test_throws)
-                    true
-                elseif extype == ErrorException && isa(exc, FieldError)
-                    Base.depwarn(lazy"Using ErrorException to test field access is deprecated; use FieldError instead.", :do_test_throws)
-                    true
-                else
-                    isa(exc, extype)
-                end
-        elseif isa(extype, Exception) || !isa(exc, Exception)
-            if extype isa LoadError && !(exc isa LoadError) && typeof(extype.error) == typeof(exc)
-                extype = extype.error # deprecated
+
+        # Handle three-argument form (type + pattern)
+        if pattern !== nothing
+            # In 3-arg form, first argument must be a type
+            if !isa(extype, Type)
+                testres = Fail(:test_throws_wrong, orig_expr, extype, exc, nothing, result.source, false, "First argument must be an exception type in three-argument form")
+                record(get_testset(), testres)
+                return
             end
-            # Support `UndefVarError(:x)` meaning `UndefVarError(:x, scope)` for any `scope`.
-            # Retains the behaviour from pre-v1.11 when `UndefVarError` didn't have `scope`.
-            if isa(extype, UndefVarError) && !isdefined(extype, :scope)
-                success = exc isa UndefVarError && exc.var == extype.var
-            else isa(exc, typeof(extype))
-                success = isequalexception(exc, extype)
+
+            # Format combined expected value for display
+            pattern_str = isa(pattern, AbstractString) ? repr(pattern) :
+                         isa(pattern, Function) ? "< match function >" :
+                         string(pattern)
+            combined_expected = string(extype) * " with pattern " * pattern_str
+
+            # Check both type and pattern
+            type_success = isa(exc, extype)
+            if type_success
+                exc_msg = sprint(showerror, exc)
+                pattern_success = contains_warn(exc_msg, pattern)
+                success = pattern_success
+            else
+                success = false
             end
+            extype = combined_expected  # Use combined format for all results
         else
-            message_only = true
-            exc = sprint(showerror, exc)
-            success = contains_warn(exc, extype)
-            exc = repr(exc)
-            if isa(extype, AbstractString)
-                extype = repr(extype)
-            elseif isa(extype, Function)
-                extype = "< match function >"
+            # Original two-argument form logic
+            # NB: Throwing LoadError from macroexpands is deprecated, but in order to limit
+            # the breakage in package tests we add extra logic here.
+            from_macroexpand =
+                orig_expr isa Expr &&
+                orig_expr.head in (:call, :macrocall) &&
+                orig_expr.args[1] in MACROEXPAND_LIKE
+            if isa(extype, Type)
+                success =
+                    if from_macroexpand && extype == LoadError && exc isa Exception
+                        Base.depwarn("macroexpand no longer throws a LoadError so `@test_throws LoadError ...` is deprecated and passed without checking the error type!", :do_test_throws)
+                        true
+                    elseif extype == ErrorException && isa(exc, FieldError)
+                        Base.depwarn(lazy"Using ErrorException to test field access is deprecated; use FieldError instead.", :do_test_throws)
+                        true
+                    else
+                        isa(exc, extype)
+                    end
+            elseif isa(extype, Exception) || !isa(exc, Exception)
+                if extype isa LoadError && !(exc isa LoadError) && typeof(extype.error) == typeof(exc)
+                    extype = extype.error # deprecated
+                end
+                # Support `UndefVarError(:x)` meaning `UndefVarError(:x, scope)` for any `scope`.
+                # Retains the behaviour from pre-v1.11 when `UndefVarError` didn't have `scope`.
+                if isa(extype, UndefVarError) && !isdefined(extype, :scope)
+                    success = exc isa UndefVarError && exc.var == extype.var
+                else isa(exc, typeof(extype))
+                    success = isequalexception(exc, extype)
+                end
+            else
+                message_only = true
+                exc = sprint(showerror, exc)
+                success = contains_warn(exc, extype)
+                exc = repr(exc)
+                if isa(extype, AbstractString)
+                    extype = repr(extype)
+                elseif isa(extype, Function)
+                    extype = "< match function >"
+                end
             end
         end
         if success
@@ -927,6 +990,13 @@ function do_test_throws(result::ExecutionResult, @nospecialize(orig_expr), extyp
             testres = Fail(:test_throws_wrong, orig_expr, extype, exc, nothing, result.source, message_only, bt_str)
         end
     else
+        # Handle no exception case - need to format extype properly for 3-arg form
+        if pattern !== nothing
+            pattern_str = isa(pattern, AbstractString) ? repr(pattern) :
+                         isa(pattern, Function) ? "< match function >" :
+                         string(pattern)
+            extype = string(extype) * " with pattern " * pattern_str
+        end
         testres = Fail(:test_throws_nothing, orig_expr, extype, nothing, nothing, result.source, false)
     end
     record(get_testset(), testres)

stdlib/Test/test/runtests.jl

@@ -107,6 +107,25 @@ end
     @test_throws "\"" throw("\"")
     @test_throws Returns(false) throw(Returns(false))
 end
+
+@testset "Pass - exception with pattern (3-arg form)" begin
+    # Test 3-argument form: @test_throws ExceptionType pattern expr
+    @test_throws ErrorException "error foo" error("error foo 1")
+    @test_throws DomainError r"sqrt.*negative" sqrt(-1)
+    @test_throws BoundsError "at index [2]" [1][2]
+    @test_throws ErrorException ["error", "foo"] error("error foo bar")
+
+    # Test with function pattern
+    @test_throws ErrorException (s -> occursin("foo", s)) error("error foo bar")
+
+    # Test output format
+    let result = @test_throws ErrorException "error foo" error("error foo 1")
+        output = sprint(show, result)
+        @test occursin("Test Passed", output)
+        @test occursin("Thrown: ErrorException", output)
+    end
+end
+
 # Test printing of Fail results
 include("nothrow_testset.jl")
 
@@ -402,6 +421,47 @@ let retval_tests = @testset NoThrowTestSet begin
     end
 end
 
+@testset "Fail - exception with pattern (3-arg form)" begin
+    # Test type mismatch
+    let fails = @testset NoThrowTestSet begin
+        @test_throws ArgumentError "error foo" error("error foo 1")  # Wrong type
+    end
+        @test length(fails) == 1
+        @test fails[1] isa Test.Fail
+        @test fails[1].test_type === :test_throws_wrong
+        @test occursin("ArgumentError with pattern \"error foo\"", fails[1].data)
+    end
+
+    # Test pattern mismatch
+    let fails = @testset NoThrowTestSet begin
+        @test_throws ErrorException "wrong pattern" error("error foo 1")  # Wrong pattern
+    end
+        @test length(fails) == 1
+        @test fails[1] isa Test.Fail
+        @test fails[1].test_type === :test_throws_wrong
+        @test occursin("ErrorException with pattern \"wrong pattern\"", fails[1].data)
+    end
+
+    # Test no exception thrown
+    let fails = @testset NoThrowTestSet begin
+        @test_throws ErrorException "error foo" 1 + 1  # No exception
+    end
+        @test length(fails) == 1
+        @test fails[1] isa Test.Fail
+        @test fails[1].test_type === :test_throws_nothing
+        @test occursin("ErrorException with pattern \"error foo\"", fails[1].data)
+    end
+
+    # Test first argument must be a type
+    let fails = @testset NoThrowTestSet begin
+        @test_throws "not a type" "error foo" error("error foo 1")  # First arg not a type
+    end
+        @test length(fails) == 1
+        @test fails[1] isa Test.Fail
+        @test fails[1].test_type === :test_throws_wrong
+    end
+end
+
 @testset "printing of a TestSetException" begin
     tse_str = sprint(show, Test.TestSetException(1, 2, 3, 4, Vector{Union{Test.Error, Test.Fail}}()))
     @test occursin("1 passed", tse_str)