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

(triggers/associations).

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.

Selenium

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 forum: Guenevere. You can use any ChoiceScript game you want: Children of the Gods: The Hero Trials, The 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:

- Selenium documentation.

- Youtube tutorial, basic level.

- Selenium tutorial, advanced level.
- Set of comprehensive Selenium tutorials, advanced level.

That's all for now. 

Cheers.

Real computer programming tutorial for writers and complete beginners

I didn't want to do this since Internet already contains millions of decent programming tutorials, but I already received 2 messages with the contents like this: 

'I usually use ${name_of_the_interactive_fiction_framework} for games development. Now I want to create something bigger. Can you tell me what should I do? Should I learn ${name_of_the_programming_language}?' 

My research of interactive fiction developers across the Internet gives me yet another intention to write this short guide since the case when those guys understand that their frameworks are complete trash when it comes to serious game development is not that rare (surprisingly for me, to be honest). Most of them then tend to just give up and remove any unique content of their projects that can't be easily implemented via particular framework.


I feel responsibility for those fellows and I know that I can show them the right way into software development. (As well as they can show me the right way into proper English. Joke. Noone can help in this case.)

Let's start!

So, your stage of easy Twine mini-games and Inform7 pseudo parsers is finished. Maybe you do have some programming experience (most likely, it's javascript), maybe you don't. 

The main problem is that usually you simply don't know what to do next. 'Probably I should read some guides' - you think. You use google and then you see strange words and symbols like 'opengl, directx, webgl, unity, cryengine, unreal engine, python, c++, java, c#, visual studio, eclipse, netbeans, qt'. You can search for tutorials and guides, but there is no easy ways to determine if a particular guide is good even if you understood it and even if you managed to copy-paste and launch some code examples. 

The probability of situation in which you find a good guide that not only gives you some advices and some working code snippets, but also explains you the essence of programming and some basics of computer science is very low. You will find some decent guides for sure, but the maximum you can achieve is an experience of solving particular tasks and problems like 'how to display pixel on the screen', 'how to display words on the screen', 'how to change font', 'how to process keyboard input' with a huge amount of gaps in your knowledge.

What you need is a systematic knowledge. Education can give you proper knowledge, of course, but it takes a lot of your time and money. The simplest way to educate yourself in my opinion is to find a good book. That's what I'll do right now - I'll present you a right book that will help you to start your programming career without crawling Internet or paying for expensive courses. It's a hard task since usually books that teach you how to program are boring and contain only theory that can be useful only for experienced readers.

Super book

This book will teach you how to create your programs from scratch. It will tell you how to use the most valuable programming language in game development - C++. It will give you a good basic knowledge of object oriented programming using this language. This book also contains cd (ye-ye) with all needed software for you to start doing real stuff. It's 'You Can Program in C++: A Programmer's Introduction' by Francis Glassborow and Roberta Allen. You can find it on wiley and on amazon. I suppose there is also pdf version available on the Internet so you can find it, read a few pages and decide if it's for you. I extremly suggest you to read 'Before purchase' section in the beginning of this book. I am sure it will properly motivate you.

Here's the important snippet: 'This book is a collaboration between me as a technically knowledgeable and experienced teacher and Roberta, whose qualifications were exactly those that a reader will need. Roberta’s contribution is small in textual content and vast in helping me to write a book that can be used by someone whose computing skills are just enough to load a program, use a word processor, use email and surf the Internet. When she started as
the student half of the authorial team, despite having used a computer for a decade she still had not grasped the concepts of directory structures and the like. Her study of mathematics ended at 16 and her mathematical skills more or less stop with simple arithmetic and those skills needed to keep a set of company accounts.'

Yes, you are right, an impossible thing happend - professional developer found 40 y/o woman who had no clue about programming and asked her to review his book! After that he rewrote every single chapter in such a way so she managed to understand everything. It's such a rare case I must admit! Now this book is the only C++ book I know that is understandable by a normal person with a zero experience in real programming.

You will learn and you will do these things

- How to write and how to launch your first program if you know nothing about programming.

- How to display some pixels on the screen. I think it's like a 'Hello World' program for game developers. This book uses it's own simple toolset so it won't be painful.

- How to process user input via keyboard and mouse.

- How to process input data like strings and numbers via command line.

- Basics of object oriented programming - classes.

- You will write a class sprite that will help you to display complex images and animation.

- You will write a class turtle. You will have a lot of fun implementing this class and playing with your results. Check this video, for example.

- You will write a class font that will allow you to display...your own font via pixels.

- You will complete hundreds of useful programming exercises that cover almost every basic aspect of C++.

Summary

You will understand this shit, I promise.

So, where is that tutorial that I promised? Real computer programming tutorial is not this article, it's the book described above that I highly recommend to you if you are a beginner who is planning to become a real software and game developer.

If you think you need to read something advanced about C++ or Java - leave a comment here or contact me via email or twiter, I have a lot of interesting and useful resources to share with you!

// Bonus for those who already knows about our game project: Dark Forest: Reborn will be written in pure C++. Moreover, natural language processing core of chatbot that we are using in Dark Forest: Reborn is written in C++, too.

Modern text-based adventure games development #3: Solutions

    Time for another post of thoughts. Previously we discussed problems that are common for modern (and not only) text-based adventure games development. Again, this is not a tutorial. I'll write some tutorials for those who are planning to develop their own games later (yes, there are tons of such tutorials already on the internet so hopefully I will change my mind and will not do that).

Looking at fellow developers that suffer from poor development tools

So, text-based adventure games usually have such problems:

1.) Poor natural language processing capabilities.
2.) Primitive gameplay and game mechanics in general.
3.) Primitive characters or even no 'real' characters at all.

    Why is it so sad? I think the roots of these problems are in interactive fiction community ideology that is obsolete. Ken Poirier from a comment section on our facebook page also added that one of the problems with text parsers is that games are often designed to be compatible with the old z-machine system. Well, this is one of the reasons. You can read about z-machine here.

    All things listed above can stop you on your way to creation of your unique text-based game. So, what can you do about that?

    Again, if you want to create simple ('traditional') interactive fiction game as fast as possible - take a look at Twine or Inform and come back later. You can also skip everything below for now.

    I see only one way of text-based games development that can help you achieve good results without forcing you to study things you will never use again:

    You can develop your text-based game like it's a real game. Yes, strangely, but text-based games are computer games too, so you can just...program text-based games using any programming language you know. This is the only way to create something really unique and the only way that gives you complete freedom in your creativity, as well as useful experience, knowledge and portfolio.

    You may think 'but why do I need to create everything from scratch and create yet another set of crutches?', and I am ready for that.

    Below are some ideas about text-based games in general. Text-based games are simple (if we talk about development process) - you don't need graphics with outstanding landscapes or cute pixel 
art characters, you don't need marvellous music, you don't need top-notch voice acting - just something that allows you to print text on the screen. And maybe a good compelling plot. Maybe.

    Let's pretend we want to create a text quest or any kind of interactive fiction. If you played some text adventure games you could see that usually the gameplay of such kind of games goes in this way: 

    Process input text-> Display output text -> Repeat

    Actually, that's all. 

    So, do we really need some special software tools like Twine, Adrift or Inform to create such a game? A lot of people are working right now developing these tools to help you to do what exactly? - request user input via text field, process (in a very simple way) received input and then just display a response.

    That's all. Literally. 

    If you need something advanced - these people and these tools will answer you 'sorry, mate, we can't do that, do it yourself'.  Maybe they can offer you natural language processing? - No, of course no. Easy-to-implement ways to create game world that is more complex than connected rooms? - No. Tools to create your NPC with replics, emotional state, memory? - You know the answer.

    You may think again (I see you like to think) 'But actually you can simplify any kind of games in this way. Crysis processes some inputs, analyzes it, displays some korean soldiers, then you hear pew-pew and that's all'. No. It's not that simple: you need graphics engine, 3d models, you need sound libraries, you need voice acting, you need animations, you need physics, you need math, you even need artificial intelligence...Not that easy to create everything solo.

    I am just saying that fellow reader can create text-based games from scratch using any programming language with it's basic functionality.

    Text-based game usually takes input strings and displays strings as answers based on some conditions. For example, your game can have such kind of conditions: current game zone, player's stats, completed quests, previously received input strings, game difficulty settings, current input string.

    Then, if your game receives 'How are you, friend?' input string, it displays output string 'Go away, animal!' doing something like this:

if (player is in zone1)
  if (player's charisma is equal to 1)
    if (player completed quest 'Have sex with Bishop's wife')
      if (previous player's replic was 'Hello, mister Bishop!')
        if (current input string icontains 'how are you')
          if (difficulty is equal to 'hardcore 18+')
            do_some_stuff(x)
           display("Go away, animal!")
          else
           do_other_stuff(y)
           display("Go away, retarded sickfuck!")

Just a bunch of simple if-clauses. Looks ugly. But this is the example of what is actually going on when you play any game - it receives some input signals and based on that signals and some constants and variables produces output:

if (variable1)
  if (variable2)
    ...
      if (variableN)
        do_simple_things()
        set_some_variables()
        display(x)

    Of course you will not write code like that. Well, if you are new to programming, you can even start with this code. In case of text-based games the amount of if-clauses is not huge. Good object oriented design will eliminate the need of this stuff and checks will be hidden. How to reduce the amount of explicitly-written conditions and write good object-oriented/meta abstract code for videogames? How to create your own game world model? What about roleplaying system? Items, objects interactions? Eventloop? Topics that are already covered in myriads of artices. But actually you can do that, and the process will be easy since it's just a text-based game. You'll still be able to focus on storytelling, replics and descriptions of things (usually it's 90% of interactive fiction development). And the development experience of doing these simple things yourself (even if you think that you produce worst code in the world) will be priceless. 

   What about natural language processing? I'll definetly write an article about some simple and useful algorithms you can use. The simplest thing you can do right now to improve players experience is to introduce synonyms checks and even simple regular expressions checks. That's right, son, don't just write 

    if inputString is equal to 'go north'

write 

    if inputString matches setOfRegexps

where setOfRegexps contains things that match 'I go north', 'I fuckin want to go north', 'I go to the north', 'I run north', 'I jump to the north'.

This is possible solution too:

    if inputString.icontains(mapOfSynonyms['go']) && inputString.icontains(mapOfSynonims['north'])

where mapOfSynonims is a map/any data structure that contains sets of your synonyms: [{'go', 'run'}, ['north', 'N'}]. Surprise - most of modern text-based games don't do that.

    Text-based game that understands 'hello' but can't understand 'hello, how are you?' fails one of the main tasks of text-based game - text processing. It was 'okay' 30 years ago. But now you need something more to impress players.

I didn't want a list of tutorials here again but, well, I feel I still need a list of resources for complete newcomers in gamedev world:

1.) Good python tutorial. Contains code for a text-based game with rooms and items.
2.) Question on stackexchange with example of game code with tons of if-clauses and tips for the ways of improving it.
3.) C++ article about writing of text adventure game from scratch.

    If you choose the way I described above - you can even say someday 'Hey, guys, I don't want text-only game anymore. I want to add awesome graphics and sound' - and you will do this, and the code you written for your text-based game will not be useless.

    That's all for now.

    Do you feel comfortable playing text adventure games with 'traditional' design? Maybe you faced problems with processing of different types of inputs with the same meaning in other types of games?

Overview of interactive fiction frameworks #1: Twine

I decided to give a brief overview of commonly used frameworks for interactive fiction and text based games development. Most of them are primitive enough to be covered on a single page. I don't want to write yet another tutorial #1000, I maybe put some links to existing ones.

I start with Twine. People who write interactive fiction nowadays like this 'framework' because it allows to create a 'game' from scratch in a minute. Literally. You don't need to be a programmer. You don't need to use your brain most of the time. You just write some passages, add some links, some variables (variables are for advanced Twine users, don't laugh, don't laugh) - and your game is ready to be published in the internet.

Psyduck uses Twine. Psyduck feels bad.

I am not saying it's bad. I am saying it's super simple. And this is bad. Simplification made too early is the worst thing in any learning process. When you learn something for the first time in your life, your mind changes significantly (as well as your brain structure, amount and strength of connections between neurons,...). And the entire perception of any advanced thing in the future will be based on your first experience and the model created in your mind. 

That's why every simple framework like Twine may be fatal for complete newcomers in games development with zero knowledge of any decent programming language techniques and patterns.

So, I want to create my first interactive fiction game. I don't know how to start, but I am clever enough to google things. I encounter Twine. What do I do now?

1.) I download and install it.

2.) I launch it:

3.) I press '+ Story', I name my story, I see this:

4.) I click on that fancy square and edit it's content:

5.) I press '+ passage'. I edit this new passage:

Now I need to connect my passages somehow. I don't see any arrows (usually in such kind of editors you use arrows to connect tiles/places/figures). Time to google! It seems you need to edit the text of a passage to make a link to another one:

6.) I add '->' after the text of my first passage. Twine suggests me the name of my second passage (so kind), but it actually fails: as you can see, it added ']]' symbols, but didn't add '[[' at the beginning. 

7.) I fix it and I see the miracle of science: arrow appears!

8.) Time to test my creation. I press 'play'.

9.) I press on the text and the game shows me the second passage: 

10.) [Optional] I cry because I have finally created something - my brand new game.

As you can see, it's pretty simple. It's simple when you need to create something simple. But if you need variables, conditions, classes and objects, events (any simple thing that you usually use during development) Twine says 'Of course you can do it, mate, but don't ask me to help!' 

And you do it. On your own. Digging javascript or using crutches that Twine suggests you to use:

- Random events

- Inventory macro

- Style changes (time to learn CSS!)

- Audio effects (time to program in javascript)

- Tons of macros. Literally. Save your eyes, don't look at them.

One girl posted a guide here describing how to create something 'advanced' using Twine.

There is even something that looks like code snippet:

(else:)[ You hit the monster!  

  (set:$monster_hp = $monster_hp - 1)  

  (if: $monster_hp < 1)[ The [[monster is dead]]! ]  

  (else:)[    

    Its health is $monster_hp.

    [[fight]] 

    [[flee|main]] ]  

]

You see conditions, you see variables. Not that bad. But why do I need to use this tool if I still have to write code in some strange programming language (and even in javascript!) to create something different from 'Hello World' example? That's why:

- You are not a beginner and you just want to create something simple and fast.

- You need to create something that will use browser as it's engine. This is probably the only reason why I could use this tool.

- You are a beginner and you want to create something simple and fast and forget about it in a hope that your brain will not be damaged.

Here's an another blog of a girl who uses Twine with tutorial and with a list of games you can play. For example, 'at the bonfire' (yeah they use dropbox to distribute their games!) Some links are broken tho.

I also suggest this blog of yet another girl, Gersandelf. It contains an article which describes really advanced Twine techniques showing the implementation of items system with really good explanations. If you decided to use Twine, check this out.

Caw caw.