nndi-oss / dialoguss

CLI tool for testing HTTP based USSD applications

Dialoguss

dialoguss is a cli tool to test USSD applications that are implemented as HTTP services - particularly those implemented via:

• AfricasTalking's service or
• Using ussd-adapter

dialoguss is useful for testing your USSD applications during development.

It can be used in two ways:

1. You can simulate a session and interact with that session via a simple CLI based interface or,
2. You can describe the steps required for a session and automate the session, i.e. automated testing

Usage

dialoguss requires a YAML file to run. The file describes one application and has to contain atleast url to the application, dial the USSD shortcode for your app and a phoneNumber to use for the session tests.

For the automated dialogue tests you are required to define steps which describe the sequence of steps for one USSD session. Steps define the text to send to the USSD application and the expected output after sending that text.

Please refer to the examples below:

Interactive Dialogue

# app.yaml
url: http://localhost:9000/ussd
dial: *123*1234#
phoneNumber: 265888123456

$ dialoguss -i -f app.yaml
Sending *123*1234# to <app>
USSD Response:
What is your name?
> name: Zikani

Hello Zikani, choose an item:
1. Account detail
2. Balance
3. Something else
# Exit
> 2

Your balance is: MK 500
> ok

Automated Dialogue

# app.yml
url: http://localhost:7654
dial: "*1234*1234#"
# 'global' phone number, overriden per session
phoneNumber: 265888123456
sessions:
  - id: 12345678910
    phoneNumber: 265888123456
    description: "Should return a balance of 500 for Zikani"
    steps:
      # The first step is the response after dialing the ussd code
      - expect: "What is your name?"
      - userInput: "Zikani"
        expect: |-
          Welcome, Zikani
          Choose an item:
          1. Account detail
          2. Balance
          3. Something else
          # Exit
      - userInput: "2" 
        expect: "Your balance is: MK 500"

$ dialoguss -f app.yml
All steps in session 12345678910 run successfully

Why should I use this?

Glad you asked! Well, mostly this tool will help you reduce costs related to testing your USSD applications. The current approach for testing your applications could be to upload the code to your server, pull out your phone and dial the USSD service code linked to your application.

That's too much work and costs you time and monies!

You should use this if you'd like to test your application before deploying it to production.

---

Copyright (c) 2018 - 2020, NNDI

dialoguss's Issues

Africastalking support should send text same as AT sends it

Africastalking support should send text same as AT sends it by concatenating the previous input with *.
A first request would have 1, second should have 1*1...

Use kong for building CLI commands

Refactor the code to use kong for building and parsing the command-line args.
This is a potentially backward incompatible change but will enable us to add other functionality to the program.

The command line should support the following subcommands initially

$ dialoguss version

$ dialoguss simulate [--file FILE] [--url URL] [--phone PHONE]

$ dialoguss run --file FILE [default:dialoguss.yml]

Support referencing steps as components to enable re-usability

Support referencing components to enable re-usability.

steps:
  - id: 1234567891011
    phoneNumber: 265888123456
    description: "Should return list of visited locations"
    steps:
      - expect: "#/components/steps/initial"
      - userInput: "2"
      
components:
  steps:
    initial: |-
      Welcome
      1. Choose a location
      2. View previous locations
      #. Exit

Show a warning when a response from a USSD operation has over 160 characters

When running in interactive mode, dialoguss should show a warning banner if the response from the USSD API returns more than 160 ASCII characters - this can help guide implementers about the amount of data they are returning in their USSD screens.

Show progress bar when running sessions concurrently

Dialoguss is able to run multiple sessions concurrently (well, sorta) we should add a progress bar for showing the results of each session separately, we can use mpb

Generate SVG preview from a session

Users should be able to generate a preview of a session as an animated SVG file. Within the animation each screen should be animated in and out, the animation will loop on itself. On screens that expect user input, it would nice to show a "typing" animation for the input.