Debug your Neoroute server

When you want to test out some new routes or events you’ve created, you might want to test them before they’re actually implemented in your client. That’s where neodebug can come in handy.

Note: If you want to write actual tests with Neoroute, you can follow this guide instead. Here we only cover manual testing.

Requirements

Neodebug builds on top of the schema generation powered by neoschema. So please follow the guide on how to set that up first. Without it neodebug will not work.

Adding neodebug to your server

Quite simple:

go get -u github.com/Liphium/neoroute/pkg/neodebug/v2@latest

The reason why neodebug is a package and not a CLI tool is actually quite simple: That way it integrates better with Magic.

But in general, this way you do not have to remember long commands and can just do a little thing like this:

go run . --debug

So, let’s get into how you get that kind of functionality.

Implementing debug functionality

In general, the entrypoint to neodebug should live in your server code or some package you have in your server (for example your_project/cmd/debug). While we usually put it in Magic scripts so we can execute it quite easily, checking for an argument or creating a separate cmd/debug folder that you can then execute with go run ./cmd/debug are both things you can do.

Neodebug actually only exposes one function, neodebug.Run. After calling it, neodebug will generate your schema and open up a debugger CLI interface. Here’s how you use the Run function:

import (
	"github.com/Liphium/neoroute/pkg/neodebug/v2"
	"github.com/Liphium/neoroute/pkg/neodebug/v2/config"
)

neodebug.Run(config.DebugConfig{
	// The command required to generate the schema for your application.
	// Default: go run . --neo-generate
	GenerateCommand: "",

	// The name of the transporter you want to connect to (from your schema).
	TransporterName: "main",

	// The URL to that transporter.
	TransporterURL:  "http://localhost:6121",
})

We hope you enjoy your new debugger. But let’s actually learn how to use it.

Presets (since v2.0.0)

With v2.0.0 of Neoroute we shipped a new feature in neodebug that allows you to define custom request presets for routes in your server.

This allows you to define templates (presets) for requests you send often directly in your config.DebugConfig and use them in the CLI. This is really useful for giving other people more tools to more easily and quickly test your application.

You can add presets in the following way:

neodebug.Run(config.DebugConfig{
	Presets: []config.Preset{
	  {
			Name: "test",
			Route: "some_route", // Whatever the name of your route is
			Data: SomeRequest{
				/* ... */
			},
		},
	},
})

A few things to keep in mind:

  • You can define invalid presets to see how neoroute handles that kind of request
  • The data you put in needs to be serializable using MessagePack
  • To be able to edit presets in neodebug (for changing the template slightly), you need to use the same struct as the request to your handler

Usage

While Neodebug is designed to be as simple as possible, it can be a little much in the beginning. Showing everything here with images is something we could do, but I think a video makes more sense here.

So go watch it: https://www.youtube.com/watch?v=EM6WdF-U8go.