Mocking a webservice CalloutException for a SOAP Fault

Question

I have a mock class for a web service that implements WebServiceMock.

With some requests the actual web service being mocked will return a SOAP Fault that results in a System.CalloutException in Apex. E.g. passing in an invalid external ID.

How can I mock the SOAP fault response that results in a CalloutException?

I have code that catches these exceptions that I'd like to test using the mock. I'd prefer not to insert special test cases in the actual code using Test.isRunningTest() to simulate the response.

A sample response from the web service looks like:

<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
   <s:Body>
      <s:Fault>
         <faultcode>s:Client</faultcode>
         <faultstring xml:lang="en-US">Validation Error(s) occurred during Foo Get.</faultstring>
      </s:Fault>
   </s:Body>
</s:Envelope>

I cannot throw a new instance of System.CalloutException. Doing so gives the error:

Type cannot be constructed: System.CalloutException

I cannot extend System.CalloutExceptions. The compiler gives me the error:

LocalCalloutException: Non-virtual and non-abstract type cannot be extended: System.CalloutException

Usually I would put an instance of the class specified in the responseType parameter into the response parameter dictionary with the key 'response_x'. I tried switching this out with a SOAP fault:

response.put('response_x', '<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/"><s:Body><s:Fault><faultcode>s:Client</faultcode><faultstring xml:lang="en-US">Validation Error(s) occurred during Foo Get.</faultstring></s:Fault></s:Body></s:Envelope>');

This resulted in a (here FooBar_element is the type specified in responseType):

System.TypeException: Collection store exception putting String into MAP<String,FooBar_element>

Answer 1

It's possible to scaffold a System.CalloutException by deserializing it into existence or instantiating it with the type. Then you can throw it in your mock:

Adrian Larson notes that as of API v36.0 you can just construct them :-)

@TestVisible class ResponseMock implements WebServiceMock {
    public void doInvoke(
        Object stub,
        Object request,
        Map<String, Object> response,
        String endpoint,
        String soapAction,
        String requestName,
        String responseNs,
        String responseName,
        String responseType
    ) {
        CalloutException e = new CalloutException();
        e.setMessage('Validation Error(s) occurred during Foo Get.');
        throw e;
    }
}

Inject it into your test with the normal HTTP mock method:

Test.setMock(WebServiceMock.class, new ResponseMock());
client.doTheCallout();

Answer 2

Just extending the findings of @mattandneil. Not trying to steal any thunder, but this is too long to be a comment.

In Creating Custom Exceptions, the documentation still claims:

Since you can’t throw built-in Apex exceptions but can only catch them, you can create custom exceptions to throw in your methods.

Despite this assertion, the compiler now allows built-in Exception types to be constructed. I confirmed through Execute Anonymous with the following snippet:

try
{
    CalloutException e = new CalloutException();
    e.setMessage('This is a constructed exception!');
    throw e;
}
catch (Exception pokemon)
{
    system.debug(pokemon);
}

I went through the whole list and what do you know? The following types can all be constructed and thrown:

• AsyncException
• CalloutException
• DmlException
• EmailException
• ExternalObjectException
• InvalidParameterValueException
• LimitException (though it still can't be caught)
• JSONException
• ListException
• MathException
• NoAccessException
• NoDataFoundException
• NoSuchElementException
• NullPointerException
• QueryException
• RequiredFeatureMissingException
• SearchException
• SecurityException
• SerializationException
• SObjectException
• StringException
• TypeException
• VisualforceException
• XmlException

Answer 3

I guess all you need to do is create a custom exception which inherits System.CalloutException. System exception cannot be thrown but their sub classes can.