Skip to content

Test Scenarios

Structured scenarios for alpha testing.

How to Use This Guide

Each scenario describes:

  1. Goal: what you're testing
  2. Setup: what you need
  3. Steps: what to do
  4. Expected: what should happen
  5. Report: what to note if something goes wrong

Every step is typed into the Urchin terminal. Commands that start with / belong to the client. Everything else is a node command, and it works the same over SSH (ssh <user>@<host> -p 8122), where you leave off any / prefix.

Work through scenarios that match your setup. Report any deviations from expected behavior. When something goes wrong, type /bug <what happened> straight away, before you do anything else.

Scenario 1: Basic Installation

Goal: Verify installer works on your platform.

Setup: Fresh machine or clean install environment.

Steps:

  1. Download the Urchin executable for your platform and urchin.pck into one folder (macOS: the zipped app bundle).
  2. Launch Urchin. On Linux, run chmod +x urchin.x86_64 first.
  3. Let the setup wizard finish without closing the window.
  4. In the Urchin terminal:
/check-updates
transport
@node_processes

Expected:

  • The wizard downloads and installs its components without error
  • Urchin opens its interface with the node running
  • @node_processes lists the daemons, and transport lists the active transports

Report if:

  • Download fails or stalls
  • The wizard stops with an error
  • A daemon you expect is not running
  • Any error messages

Scenario 2: Identity Creation

Goal: Verify identity system works.

Setup: Urchin installed (Scenario 1).

Steps:

  1. On the welcome screen, enter a username and choose Create Identity.
  2. Set a password and a theme.
  3. When you land in the terminal:
whoami
@whoami

Expected:

  • Registration completes without error
  • whoami shows your name with its discriminator (the part after #)
  • @whoami shows your peer-to-peer identity
  • On a new node this first account is the node's owner

Report if:

  • Registration fails with error
  • The discriminator is missing or malformed
  • Any error messages

Scenario 3: Room Creation and Navigation

Goal: Verify world management.

Setup: Identity created and logged in.

Steps:

look
go public
create ~room garden
create ~room lounge

Each reply names the exit into the new room and the exit back to the zone. Rooms must be created in a zone, so a create ~room typed inside a room is refused with a hint. Then:

go garden
look

Use the exit name the reply gave you to walk back to the zone, then:

go lounge
look
list rooms

Expected:

  • Rooms create successfully
  • look shows the correct location and its exits
  • Navigation works in both directions
  • list rooms shows both rooms

Report if:

  • Creation fails
  • look shows wrong location
  • Navigation fails
  • Exits don't appear

Scenario 4: Persistence

Goal: Verify state survives restart.

Setup: Rooms created (Scenario 3).

Steps:

list rooms
/exit

Closing the last Urchin window stops a node that Urchin started. Relaunch Urchin, log in, and run:

list rooms
home
go public
go garden
look

Expected:

  • All rooms still exist
  • Exits still work
  • Capsules still exist

Report if:

  • Rooms are missing
  • Data is corrupted
  • Different state than before shutdown

Scenario 5: Local Network Connection (mDNS)

Goal: Verify LAN discovery and connection.

Setup: Two machines on the same network, both running the same Urchin release, each with its own account.

Steps:

On both machines, note your name with whoami, then:

@discover

The other machine should appear, marked ✓ once its signed hello is verified. If it does not, wait 30 seconds and retry.

On Machine A:

create ~presence plaza
invite plaza -short

Note the short code. On Machine B:

join <code>

On both machines, with the other machine's name:

ping <name>
@peers

Expected:

  • @discover shows the other machine under the name its hello proved
  • join succeeds
  • ping shows mDNS: connected
  • @peers tags the other machine [mDNS]

Report if:

  • Local discovery fails
  • Connection fails
  • The peer appears under a name other than the one whoami shows on that machine

Scenario 6: Internet Connection (Veilid or Tor)

Goal: Verify cross-internet connection.

Setup: Two machines on different networks.

Steps:

On both machines:

@node_processes
@veilidstatus
@torstatus

On Machine A:

create ~presence plaza
invite plaza -short

On Machine B (different network):

join <code>

On both machines, with the other machine's name:

ping <name>

Expected:

  • Veilid and Tor show as running on both machines
  • Connection succeeds (the first connection can take a minute or more)
  • ping shows Veilid: connected (handshake complete) or a Tor line of connected

Report if:

  • Veilid or Tor is not running
  • Connection timeout
  • Excessive delay on messages (more than a few seconds)

Scenario 7: Messaging

Goal: Verify CapTP messaging works.

Setup: Two connected machines (Scenario 5 or 6), both in plaza.

Steps:

On Machine A:

chat Hello from A

On Machine B, the message should appear with A's name. Then:

chat Hello from B

On Machine A, the message should appear with B's name.

Expected:

  • Messages appear on the other machine within a few seconds
  • Sender identity is correct
  • No message loss

Report if:

  • Messages don't arrive
  • Messages arrive but corrupted
  • Wrong sender identity
  • Significant delay (>5s)

Scenario 8: Network Interruption

Goal: Verify system handles transport changes.

Setup: Two machines connected (Scenario 6).

Steps:

On Machine A:

ping <name>
@health

Disconnect Machine A from the network (turn off Wi-Fi or unplug the cable) for 60 seconds, then reconnect it. Wait two minutes, then:

ping <name>
@health
chat Test after reconnect

Expected:

  • Urchin and the node keep running while the network is down
  • @health shows the session and reconnect state
  • The connection comes back without a new join

Report if:

  • Application crashes
  • Permanent disconnection
  • You have to join again to reconnect

Scenario 9: Error Handling

Goal: Verify graceful error handling.

Setup: Logged in.

Steps:

go nowhere
join nosuch-code-00
grant nosuchcapsule someone#0000 read

Then type /exit, relaunch Urchin, and log in with a wrong password.

Expected:

  • Clear error messages
  • No crashes
  • Ability to retry, and a correct password works after the wrong one

Report if:

  • Crashes or hangs
  • Unclear error messages
  • Unrecoverable state

Scenario 10: Stress Test (Optional)

Goal: Find edge cases under load.

Setup: Two connected machines (Scenario 7).

Steps:

  1. On both machines, send chat messages as fast as you can type them for a few minutes.
  2. On one machine, create twenty rooms in a zone with create ~room room1, create ~room room2 and so on.
  3. Leave both machines connected for an extended period (1+ hours), and watch the Urchin and node processes in your system's task manager.

Expected:

  • System remains responsive
  • No steady memory growth
  • All messages delivered

Report if:

  • System becomes sluggish
  • Messages lost
  • Memory usage grows unbounded

Reporting Results

See Reporting Issues for how to report test results.