Debugging Guide

ITP Debugging Guide

First, think about the failure mode (how the test is going wrong): 1. If a spec or validation test is failing, that suggests that there might be a problem with the content of the message. 2. If a test step is not being recognised at all, that suggests that there might be a problem with the routing of the message.

Content Problem

1. If it's a content problem, look at the (request or response, depending on what failed) message body. Often this is not a subtle failure (like a value of 5 instead of 6), but rather a wholesale different body - e.g. an HTTP 500 error instead of the expected payload. Looking at the message body will probably give you a good idea of what exactly the problem is.
2. If it's a problem with the response (which is more common), try to use the Copy cURL button to run the request for yourself, and see if you get the same (incorrect) response. You should do! You can import the cURL into Postman and tweak the request to see if there's something wrong with the request payload that is causing an error in the response.
3. If the payload body doesn't give you enough information, it might be worth adding some logs to the request handler.

Routing Problems

The most common cause of routing problems by far is incorrect URL configurations. Check the .env file to make sure that the URLs match those displayed on the platform. Check for the s in https. Check for a trailing /. Check that the session and component UUIDs are all as they should be. Then check again!

If everything looks correct in the URL, you will need to add some logging to see where the message is dropping. Broadly, there are two causes to investigate:

1. The incoming message isn't being received or processed for some reason. In this case, it's worth checking the component responsible for the sending that message, to ensure that it is well-formed, and has a correct URL etc.
2. The handler is crashing before it can respond or send an onward message. In this case there may already be an error message visible in the laravel log. If not, try to add your own log as early as possible in the method handler. If that message appears, progressively move the log down a few lines and rerun the handler until you find the point that things are going wrong.

Logging

Logs are your friend! If it looks like some code isn't working the way you expect it to, add some logs. In PHP/Laravel, you can do this like so:

// At the top of the file
use Illuminate\Support\Facades\Log;

// in the problematic area
Log::info("This is a debugging message!");

Laravel will output this to the storage/logs/laravel.log file. You can manually clear this file to better see when something changes.

Where to log?

You should be able to determine where the relevant HTTP handler is by looking at src/routes/api.php or src/routes/app.php. Find the relevant path for the request you're looking at, then search the whole codebase for the name of the controller. For example, in the following example, I would be looking for the method called store in a class called TransactionsController:

Route::post('/transactions', 'TransactionsController@store')->name('transactions.store');

Remote Logging

Ideally you would reproduce the error locally, and then it's easy to add logs in this way. If the error only manifests in a deployed environment, you can still add logging by following the steps below. Note that it's really not advisable to do this in a production environment, where you might accidentally break something for other users!

1. SSH into the host machine: ssh ubuntu@staging.interop.gsmainclusivetechlab.io
2. Check the docker containers running: docker ps (often you are interested in the app container).
3. Open a shell inside the relevant container: docker exec -it <container_id_here> bash
4. Edit the file you think might have a problem using a terminal editor, and add some logs: nano src/app/Http/Request.php
5. Open the log file and watch for changes: tail -f src/storage/logs/laravel.log.
6. Execute your request and see the logs appear.