Fiddler has long been the tool of choice for developers and testers who are building and verifying APIs exposed over HTTP(S). In this post, we’ll explore the existing features Fiddler offers for API Testing and announce new capabilities we’ve released in Fiddler 2.6/4.6.
The Composer tab enables the authoring of arbitrary HTTP(S) requests using any HTTP method, url, headers and body, and the many Inspectors permit examination of responses of any type, including XML, JSON, BSON and myriad other formats. Over the last few years, the power of the Composer has grown, and it now offers many conveniences, including a Request History pane:
… to allow simple reuse of existing requests. The powerful Scratchpad tab allows you to easily display a list of requests and execute those requests as needed—a great feature for live demonstrations of your API for tech talks and the like:
As you can see in the screenshot above, the Scratchpad even supports executing requests expressed curl syntax, so you can easily exercise APIs that are documented in terms of the parameters passed to that popular tool.
Of course, Fiddler is best known as a proxy debugger, and its ability to capture traffic from nearly any source means the fastest way to generate API tests is to simply capture the API traffic from an existing client and modify and augment those tests as desired. You can start with a baseline of the calls your clients presently send, and add new tests to probe for performance, security, error handling and other problems.
One of the most powerful capabilities Fiddler offers is capture of traffic from almost any device (iOS, Android, Windows, Mac and so on); you can easily exercise your mobile clients’ API endpoints without adding any new software to the device itself!
After you’ve collected a set of requests in Fiddler, you can easily save them to a Session Archive Zip (.saz) file for convenient reuse at any time. To resend the traffic, just load the SAZ file, select the desired requests and use the Replay submenu on the Web Sessions list’s context menu to resend the requests. Common choices include:
Of these options, the last is perhaps the most interesting—you can very easily regression test an API set by simply collecting “good” traffic in a SAZ file and then using that traffic as a baseline against which later verifications will be conducted. The verification performed is rather crude, which is why we’re excited to announce…
The new APITest extension to Fiddler greatly enhances its power to validate the behavior of web APIs. Click View > Tabs > APITest to show the APITest tab. The bulk of the tab displays a Test List, a list of API requests and Validators.
Tests can be added to the list by simply dragging and dropping Sessions from Fiddler’s Web Sessions list. You can then use the context menu to specify a Validator and optionally mark it with a Note (comment) and optionally assign it to a group.
Validators offer a lightweight way to judge the success or failure of a test, and support many of the same operators used by Fiddler’s AutoResponder feature. As seen in the screenshot above:
In addition to the EXACT: operator prefix, the REGEX: and NOT: prefixes are also supported for text searches:
The HEADER: prefix allows you to ensure that the response bears a specified header containing a given value (for example, HEADER:Content-Encoding=gzip ensures that the response has a Content-Encoding header showing that the response used GZIP compression).
The SCRIPT: prefix allows you to specify a FiddlerScript function in your CustomRules.js file to use to evaluate the response; the named function is passed both the test Session and the baseline (original) Session and can evaluate any criteria you like to return whether or not the test has passed. Beyond examining the headers and body of the response, you could, for instance, evaluate the values in the Session’s Timers object and fail the test if the response took more than 100 milliseconds.
// This method is called by "SCRIPT:CheckTest" validators; it
// returns TRUE if the Test passes, and false otherwise.
static function CheckTest(oRun: Session, oBase: Session): boolean
{
// Simplest possible validator
if (oBase.responseCode != oRun.responseCode)
{
oBase["api-lastfailreason"] = "Mismatched status code...";
return false;
}
var timeTotal = 0;
timeTotal = (oRun.Timers.ServerDoneResponse - oRun.Timers.ClientDoneRequest).TotalMilliseconds;
if (timeTotal > 100)
{
oBase["api-lastfailreason"] = "Performance Too slow...";
return false;
}
return true;
}
Before your Test List is run, the BeforeTestList method (if present in your FiddlerScript) is run, permitting you to adjust the requests as needed:
static function BeforeTestList(arrSess: Session[]): boolean
{
// In this method, you can do any setup you need for the test,
// e.g. adding an Authorization: token OAUTH value that you
// obtained programmatically...
var sOAUTHToken = obtainToken();
if (String.IsNullOrEmpty(sOAUTHToken)) return false;
for (var i: int=0; i<arrSess.Length; i++)
{
arrSess[i].oRequest["Authorization"] = sOAUTHToken;
}
MessageBox.Show("Token Set. Running " + arrSess.Length.ToString() +
" tests.", "BeforeTestList");
return true; // Test should proceed; return false to cancel
}
After all of the individual test cases are executed, the AfterTestList method allows you to validate any post-conditions, log the results of the Test list or perform other operations. The method is passed a TestListResults object which contains an enumerable list of TestResult objects. Each result contains the baseline (original) Session, the test Session and an IsPassing boolean indicating whether the test passed. The WriteFailuresToSAZ convenience method will write all failing TestResults to a SAZ file for later analysis.
static function AfterTestList(listResults: TestListResults)
{
for (var oResult in listResults)
{
FiddlerApplication.Log.LogString(oResult);
}
listResults.WriteFailuresToSAZ("C:\\temp\\lastfailure.saz");
}
A Test List is simply a set of Sessions each of which contains several custom Session Flags (api-testitem, api-Validator, api-LastResult, and api-LastFailReason). As a consequence, these lists can be saved and loaded as regular SAZ files; their “Test List” functionality only lights up when loaded into the APITest tab using its context menu. The menu commands are largely self-explanatory:
You can temporarily disable one or more tests from running by pressing the spacebar with the desired tests selected.
While the new APITest extension offers powerful functionality, many larger enterprises instead choose to use the FiddlerCore .NET Class Library to build their API Testing infrastructure. FiddlerCore allows you to fully customize the behavior of your testing logic, driving the test using the .NET Language of your choice (typically C#). Because FiddlerCore does not utilize any of Fiddler’s UI, it can easily be integrated into existing test automation suites and can be used in console and service applications.
The Fiddler-native Session Archive Zip file format is supported by Telerik Test Studio’s Load Testing product, allowing you to simply import a SAZ file that exercises your API set, configure the number of virtual users and run time, and generate load instantly or on the schedule you set. If you’d like to apply validation logic while your server is under load, run the Load Test in Test Studio solution and in parallel execute your Test List in Fiddler.
We hope you find Fiddler’s API Testing support useful, and we look forward to your feedback as we continue to enhance the tool.
Eric Lawrence (@ericlaw) has built websites and web client software since the mid-1990s. After over a decade of working on the web for Microsoft, Eric joined Telerik in October 2012 to enhance the Fiddler Web Debugger on a full-time basis. With his recent move to Austin, Texas, Eric has now lived in the American South, North, West, and East.