Simulation

You can simulate your application right inside USSDK from the Sim tab. This saves a lot of time and helps iterate way faster.

The Sim experience helps you:

• Test your application right from the browser so you don't have to manually dial the code on your phone to check.
• Review step interactions: you're able to view for each step what input you made and the response from your hooks. This can help you diagnose issues fast.
• Save completed sessions and run them again later.
• Check if a change has broken a flow that used to work.

The Sim aims to be a 1:1 representation of how a live USSD experience will happen.

Running a simulation

Open your app in the editor and select the Sim tab. USSDK starts a new session for you automatically. You can then enter responses the same way a user would enter them on a phone.

Each simulation has a session id. This is useful when you're checking hook requests, logs, or anything else that depends on the current session.

To start again, click Restart. This creates a fresh session and starts the app from the beginning.

Phone number

By default, USSDK uses a random phone number for the simulation. If you want to test a flow with a specific phone number, click the session id at the top of the Sim tab and enable Use custom phone.

This is useful when your hook depends on the user's phone number. For example, you may want to test a returning customer, an account lookup, or an authorization rule that only works for a known phone number.

When a hook is called from the simulator, the session network is sent as sim.

{
  "session": {
    "msisdn": "0240000001",
    "network": "sim",
    "serviceCode": "*123*45#"
  }
}

Sim history

As you move through the session, USSDK records the history of the simulation. This includes:

• The step that was rendered
• The input you entered
• The hook URL that was called
• The hook status
• The data returned by the hook

You can click a history item to jump to that step on the canvas. This makes it easier to understand where a response came from, especially when a hook returned unexpected data.

Saving simulations

When a simulation reaches the end of the session, you can save it. Saved simulations are stored under Saved Sims in the Sim tab.

A saved simulation stores the inputs you entered and the output USSDK showed at each step. You can think of it as a simple test case for your USSD flow.

For example, if you have a registration flow, you can complete it once with sample inputs and save that session. Later, after changing a message, hook, menu item, or connection between steps, you can run the saved simulation again to check if the flow still behaves as expected.

You can double click a saved sim name to rename it. Use names that describe the path you're testing. For example:

new_customer_registration
wrong_pin_retry
balance_check_success
event_rsvp_with_guests

Running saved simulations

Saved simulations can be run one at a time, or all together.

When USSDK runs a saved simulation, it starts a fresh session and replays the saved inputs. At every step, it compares the message shown by the app with the message that was saved earlier.

If everything matches, the sim passes. If something changes, USSDK marks the sim as failed and shows you what went wrong.

This helps you catch regressions early. You don't need to remember every path you tested manually. Save the important ones and run them again when you make changes.

Step-by-step mode

Sometimes you don't want to run a saved simulation all at once. You may want to inspect what happens after each input.

Use step-by-step mode from a saved sim to move through the saved session one step at a time. This is useful when you're debugging a hook response, checking dynamic menu rendering, or trying to understand the exact screen where the flow changes.

Understanding failures

A saved simulation can fail when:

• The message shown by the app does not match the saved message
• The session ends before the saved simulation is complete
• The simulation request fails

For message changes, USSDK shows the expected message and the actual message. You can also view a diff to quickly see what changed.

This is especially helpful when you're working with dynamic messages from hooks. A small difference in returned data can change the screen, and the simulator helps you find that difference faster.

When to use simulation

Use the Sim tab while building and before deploying.

It works well for:

• Checking that menus and custom inputs behave correctly
• Testing hooks and hook error responses
• Testing flows that depend on the user's phone number
• Saving important paths as reusable test cases
• Replaying saved paths after changing steps, hooks, or environment variables

If the Info tab shows unresolved issues, fix them first. Some issues can prevent the simulator from proceeding correctly.