Debug Terminal Test Plan - UQcsse3200/2026-studio-3 GitHub Wiki

Debug Terminal Test Plan

Team 5, Sprint 3 | Formal automated and manual test plan for terminal input, parsing, screen wiring and cheat commands

This plan complements Debug Terminal — Commands and Cheats. It records what each case proves, why it exists, its normal/boundary/invalid condition, expected behaviour and actual evidence. A command is not treated as verified merely because it compiles or appears in a command list.

Scope and Test Policy

Production components in scope are:

  • Terminal, TerminalDisplay, KeyboardTerminalInputComponent and TouchTerminalInputComponent;
  • Battle and Map screen command registration and F1 input wiring;
  • DebugCommand, SkipBattleCommand, GiveGoldCommand, SetHealthCommand, GiveItemCommand, UnlockNodeCommand, ListNodesCommand, GotoCommand and DiscoverAllCardsCommand;
  • the real game services each command invokes, rather than mock-only replacement game flows.

Deterministic parser and command behaviour should receive JUnit coverage. Scene2D rendering, keyboard focus, screen transitions and the visible gameplay consequences need a live manual check. Each manual case remains pending until a tester records the build/commit, date and screenshot or video evidence.

Run the existing terminal tests from source/:

./gradlew core:test \
  --tests "*TerminalTest" \
  --tests "*KeyboardTerminalInputComponentTest" \
  --tests "*TouchTerminalInputComponentTest"

On Windows, use gradlew.bat in place of ./gradlew.

Automated Test Cases

ID Component / test Why this case exists Case type Input or steps Expected result Actual result / evidence
DT01 TerminalTest The parser is the boundary through which every cheat command is reached. Normal / invalid Register commands; submit no-argument and multi-argument messages; edit/backspace the input. Registered commands receive the correct arguments; unknown commands return false; input state is cleared only through the documented terminal flow. Pass — existing TerminalTest.
DT02 KeyboardTerminalInputComponentTest F1 must toggle the terminal without leaking gameplay keystrokes while the terminal is open. Normal / boundary Press F1 twice; type letters, Backspace and Enter while open and closed. F1 toggles; typed characters, Backspace and Enter are forwarded only when open; other key events are consumed only while the terminal is open. Pass — existing test.
DT03 TouchTerminalInputComponentTest Touch input must use the same terminal state and message-processing contract as keyboard input. Normal Open/close the terminal and submit text through touch input. Terminal state and submitted message match the core terminal contract. Pass — existing test.
DT04 KeyboardTerminalInputComponentTest extension giveitem ENERGY_CRYSTAL depends on underscores reaching the parser. Boundary Type giveitem ENERGY_CRYSTAL character by character. _ is appended and the command parser receives the full enum token. Pending — implementation accepts _, but no focused automated assertion exists yet.
DT05 KeyboardTerminalInputComponentTest extension Hyphenated IDs require - to reach the parser if a future command such as start-event is exposed. Boundary Type a message containing -. The agreed terminal-input contract must be documented and tested. Current merged input rejects -; do not document hyphenated commands as usable until this is changed and tested. Open implementation/documentation gap.

Command Cases

ID Command and component Why this case exists Case type Input or steps Expected result Actual result / evidence
DC01 debug on / debug off — DebugCommand Debug overlays must toggle without accepting arbitrary arguments. Normal / invalid Run debug on, debug off, debug, and debug maybe. The render debug flag changes only for one valid on or off argument; invalid forms return failure and do not change state. Pending dedicated command test and live evidence.
DC02 skipbattle — SkipBattleCommand Testers need a fast win path that still uses the real battle-outcome transition. Normal / invalid Run skipbattle during a battle, then try it with an extra argument. All enemies are defeated through BattleController; the normal victory flow occurs once; extra arguments fail without ending the battle. Pending dedicated command test and live evidence.
DC03 givegold <amount> — GiveGoldCommand Gold changes must reach the actual player inventory, not a terminal-only value. Normal / invalid Run givegold 25, then non-numeric and wrong-arity inputs. Valid numeric input changes the player's current gold; malformed input returns failure and leaves it unchanged. Pending dedicated command test and live evidence.
DC04 sethealth <amount> — SetHealthCommand Health testing needs a direct but component-safe setup path. Normal / invalid Run sethealth 1, then non-numeric and wrong-arity inputs. Valid input delegates to CombatStatsComponent; malformed input fails without mutation. Pending dedicated command test and live evidence.
DC05 giveitem <ItemType> — GiveItemCommand Item-effect testing must exercise the real ItemEffectApplier. Normal / invalid Run giveitem ENERGY_CRYSTAL, giveitem IRON_AEGIS, then an unknown item and wrong arity. Valid enum names apply the matching live-player effect; unknown names fail safely. This command applies an effect directly and does not add an owned item to PlayerRunState. Pending dedicated command test and live evidence.
DC06 unlocknode <id> — UnlockNodeCommand A node must become both available and reachable from the current node. Normal / invalid Unlock a locked node, an unknown ID, an already available node, and a non-numeric ID. A valid locked node becomes AVAILABLE and is connected to the current node; invalid targets fail without changing the graph. Pending dedicated command test and live evidence.
DC07 listnodes — ListNodesCommand Map debugging requires a deterministic node listing and must handle no active map safely. Normal / invalid Run with a map, with extra arguments, and with no active graph. Valid use logs every node in node-ID order; invalid/no-map invocation fails without mutation. Pending dedicated command test and live evidence.
DC08 goto <floor> <roomtype> — GotoCommand The shortcut must invoke the production node-selection path rather than fake a screen change. Normal / boundary / invalid Jump to an eligible combat, elite or campfire node; retry a completed/current node; use invalid floor or room type. The command finds an eligible node, connects/unlocks it if needed, then calls the real selection controller; invalid or unavailable targets fail safely. Pending dedicated command test and live evidence.
DC09 discoverallcards — DiscoverAllCardsCommand Card Library testing needs a fast, real discovery-state setup path. Normal / invalid Run with no arguments, then with an unexpected argument. All registered card IDs become SEEN; unexpected arguments fail and do not change discovery state. Pending dedicated command test and live evidence.

Manual Screen-Wiring Cases

ID Purpose Steps Expected result Actual result / evidence
DM01 Confirm terminal availability on supported screens. Open a Battle screen and a Map screen; press F1; repeat after navigating away and back. The visible terminal opens once per F1 press, accepts input and closes after a successful command without duplicated UI or input handling. Pending manual execution.
DM02 Confirm command feedback and real game effects. Run DC01–DC09's normal paths in a live build, returning to the relevant Library or encounter after each command. Logs and visible state agree: battle ends normally, HUD values update, map selection transitions, and Card Library shows all cards after discovery. Pending manual execution; attach a short walkthrough or screenshots.
DM03 Confirm invalid input is safe. Submit each command's malformed form and an unknown command while on its supported screen. No crash, no unintended battle/map/player mutation, and the terminal remains usable for the next command. Pending manual execution.

Exit Criteria

  • Existing DT01–DT03 tests pass on the final commit.
  • Focused automated tests are added for DT04 and every command case that can be isolated without a live renderer.
  • DM01–DM03 have recorded actual results and evidence on the merged main build.
  • The hyphen-input status is resolved: either accept and test it, or remove/avoid hyphenated command documentation.
  • Any failing command is linked to an issue and re-tested after the fix.
⚠️ **GitHub.com Fallback** ⚠️