Test Web Request Handlers

You can use the testing interface in the Production Server Compiler app to test web request handlers for deployment to MATLAB^® Production Server™. A web request handler consists of MATLAB functions and a JSON file that specifies URL routes. To set up the testing interface for web request handlers, you configure access to the routes JSON file.

For configuring access to the routes file, either set an environment variable that specifies the path to the routes file or place the routes file in the MATLAB preferences directory. When you start the testing interface, it searches for the environment variable for the routes file first. If the environment variable is not set, then the testing interface searches the MATLAB preferences directory for the routes file. After you configure access to the routes file, you can test the MATLAB functions for web request handlers. For more information about web request handlers, see Handle Custom Routes and Payloads in HTTP Requests (MATLAB Production Server).

Set Environment Variable for Routes File

Set the environment variable PRODSERVER_ROUTES_FILE to a value that contains the path to the routes file. You can set the environment variable at the MATLAB prompt using setenv or at the system command prompt using syntax specific to your operating system.

setenv('PRODSERVER_ROUTES_FILE', 'path/to/routes/file/routes.json');

If you specify a relative path to the routes file, from the MATLAB prompt, navigate to the folder that contains the routes file before you start the test server in the Production Server Compiler app.
If you update the contents or location of a routes file that is already in use, for your changes to take effect, restart the test server in the Production Server Compiler app.
To turn off testing for web request handlers, set PRODSERVER_ROUTES_FILE to an empty value.

Use MATLAB Preferences Folder for Routes File

An alternate option for configuring access to the routes file is to copy the file to the MATLAB preferences folder. This configuration persists across MATLAB restarts. You must name the routes file prodserver_routes.json. To locate your preferences folder, type prefdir at the MATLAB prompt.

If you update the contents or location of a routes file that is already in use, for your changes to take effect, restart the test server in the Production Server Compiler app.
To turn off testing for web request handlers, rename or move prodserver_routes.json from the preferences folder.

End-to-End Setup to Test Web Request Handlers

Create Routes File

Using a text editor, create a routes JSON file to map client requests to the MATLAB web request handler functions. Save the file as routes.json.

The following routes file maps any client request that contains MyDemo in the request URL to a hellowh MATLAB function in the whdemo deployable archive.

{
  "version": "1.0.0",
    "pathmap": [
        {
            "match": "^/MyDemo/.*",
            "webhandler": {
                "component": "whdemo",
                "function": "hellowh"
            }
        }     
    ]
}

Configure Access to Routes File

From the MATLAB prompt, set the environment variable PRODSERVER_ROUTES_FILE to specify the path to the routes file.

setenv('PRODSERVER_ROUTES_FILE', 'J:\routes.json');

Write MATLAB Function for Web Request Handler

To work as a web request handler, a MATLAB function must accept one input argument that is a scalar structure array, and return one output argument that is a scalar structure array.

The following code shows a MATLAB function, hellowh.m, that uses the input argument structure request, whose fields provide information about the request headers and body. The function also constructs and returns the structure response, whose fields contain a success HTTP code and status message, custom headers, and a message body.

function response = hellowh(request)
    disp(request);
    disp('request.Headers:');
    disp(request.Headers);
    bodyText = char(request.Body);
    disp('request.Body:');
    if length(bodyText) > 100
        disp(bodyText(1:100));
        disp('...');
    else
        disp(bodyText);
    end

    response = struct('ApiVersion', [1 0 0], ...
                      'HttpCode', 200, ...
                      'HttpMessage', 'OK', ...
                      'Headers', {{ ...
                        'Server' 'WebFunctionTest/1'; ...
                        'X-MyHeader' 'foobar'; ...
                        'X-Request-Body-Len' sprintf('%d', length(request.Body)); ...
                        'Content-Type' 'text/plain'; ...
                      }},...
                      'Body', uint8('hello, world'));
   
    disp(response);
    disp('response.Headers:');
    disp(response.Headers);
end

Prepare for Testing

Open the Production Server Compiler app by typing the following at the MATLAB command prompt:
```
productionServerCompiler
```
In the Type section of the toolstrip, select Deployable Archive (.ctf).
Specify the MATLAB functions to deploy.
1. In the Exported Functions section of the toolstrip, click the plus button.
2. Using the file explorer, locate and select the hellowh.m file.
Click Test Client. The app switches to the TEST tab.
Click Start to start your test. The Server Log section displays errors, if any.

Call Web Handler MATLAB Function

Use a client of your choice to invoke the deployed function.

The following command uses cURL to invoke the deployed function from the system command line.

curl -v http://localhost:9910/MyDemo/this/could/be/any/path?param=YES

You see the following output at the system command line:

*   Trying ::1...
* TCP_NODELAY set
* Connected to localhost (::1) port 9910 (#0)
> GET /MyDemo/this/could/be/any/path?param=YES HTTP/1.1
> Host: localhost:9910
> User-Agent: curl/7.55.1
> Accept: */*
>
< HTTP/1.1 200 OK
< Server: WebFunctionTest/1
< X-MyHeader: foobar
< X-Request-Body-Len: 0
< Content-Type: text/plain
< Content-Length: 12
< Connection: Keep-Alive
<
hello, world* Connection #0 to host localhost left intact

Examine Data

Switch back to the Production Server Compiler app.
In the testing interface, under MATLAB Execution Requests, click the completed message in the app to see the values exchanged between the client and MATLAB.
Click Input to view data passed into MATLAB.
Click Output to view data returned to the client.

After you are satisfied with your testing, you can package the MATLAB function and deploy it to the server. For more information, see Create Deployable Archive for MATLAB Production Server.