Dark Forest Crow Notes - Interactive fiction, text-interactions based and roleplaying games

Tuesday, September 20, 2016

Automated testing of choice-based text adventures (ChoiceScript / Selenium example)

If you write something complex and unique (I am sure you do), you need to test your creation. Testing of text-based games is a trivial task for software developer. This article contains some advices for regular writers without programming experience and for users of Twine or ChoiceScript.

Of course, there's an official way of ChoiceScript automated testing using Randomtest or Quicktest. My way is different and includes interactions with browser. 

You can achieve something like this (5 minutes effort)
Interactive fiction or text adventure game is just a combination of states (contexts/levels/zones/rooms) with several choices

What do you need to test? Your game takes user strings or choices as an input and generates some strings as an output. Usually, the only thing you need to test is the behaviour of your game in case of different inputs:

expected input -> expected output + postconditions

Your task is to prepare a set of different inputs and corresponding expected outputs. Your goal is to be able to send an input to your game and check its output automatically. It's very important to be able to check the functionality of your game instantly so if you change something in the middle of your 100 rooms/states and 100000 words before the release, broken transition from state 42 to state 24 will not be a surprise for you and for your players.

Example of abstract test cases

Your game starts with the question 'Do you like apples?' and some choices: 'Yes', 'No', 'I prefer oranges'.

- Choice 'Yes' leads to the state with text 'That's great!' and sets the variable 'PlayerLikes' to 'Apples'
- Choice 'No' leads to 'That's sad. I am going to shoot you down.' and sets the variable 'IsPlayerAlive' to false
- Choice 'I prefer oranges' leads to 'I love oranges too, puddin!' and sets the variable 'PlayerLikes' to 'Oranges'

Possible test cases:

- If player chooses 'Yes', text 'That's great!' is displayed.
- If player chooses 'No', text 'That's sad. I am going to shoot you down.' is displayed.
- If player chooses 'I prefer oranges', text 'I love oranges too, puddin!' is displayed.
- If player chooses 'Yes', variable PlayerLikes contains string 'Apples'.
- If player chooses 'No', variable IsPlayerAlive is equal to false.
- If player chooses 'I prefer oranges', PlayerLikes is equal to 'Oranges'.
- If player chooses 'No', game is finished.

Actually, 'text is displayed' means 'game switched its state/room and performed the first action in that state - displayed some text'.
It's all the same if your game parses text. You always have a limited number of choices (input phrases) and limited number of 
transitions and postconditions (set variable X to Y and so on).

It's not always necessary to write every possible test case - just choose the most important and crucial ones. Your test suite should perform these operations automatically and display a report with each test case's status: success/fail.


How to achieve that? I'll show you how to create your automated tests for web-based interactive fiction and text adventures using special set of tools - Seleninum. I will cover the simplest way of writing tests with the help of Selenium plugin for Firefox. You can achieve the same effect using standalone version of Selenium toolset, but it won't be that easy.

Let's rock:

0.) Install Firefox ;) 

1.) Install Selenium IDE plugin. Go to addons.mozilla.org and press the 'Add to Firefox' button.

2.) After the installation process, check 'tools' menu: Selenium IDE field will appear.

3.) Press 'Selenium IDE' to launch test suite.

Launched Selenium window
Let's write some tests? I picked a game I found on the ChoiceScript forumGuenevere. You can use any ChoiceScript game you want: Children of the Gods: The Hero TrialsThe Seven Heirs of Ophaesia, ${your_game_name}.

The main thing you need on the first step is the link to your game.
Fill the fields 'Command' and 'Target' in the Selenium IDE window:

You need to set 'Command' field to 'open' and 'target' to 'link to your game' like on the screen above. Now press the green arrow to launch your first test.

Your first test checks the ability of your game to show its start page.

Recording your actions

Let's add some transitions. Press the record button (red, top right corner). Selenium will start recording your actions. Time to play!

I am pressing random buttons, but you can plan your actions and record the most important or buggy way of playing your game. Press the red button again to stop recording.

Selenium is ready to reproduce recorded actions.

I switched the execution speed to 'slow' and pressed the green arrow button to perform my test:

It's alive!

I guess you understand that now you can actually create a test that goes through the entire game. You can write as many test cases as you want. You may notice a list of strange lines of text on the right side of the Selenium plugin window:

It's the list where you can find every command executed by Selenium. You can add your commands by 'recording' them or you can add them manually. 

Additional test cases

Let's add a command that checks the presence of a particular string on the screen:

Don't forget to save your test:

I described the simplest way to automate testing process of your choice-based interactive fiction.

Here is the list of useful resources:

That's all for now. 


1 comment: