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.

Combat system in Dark Forest: Reborn

'Well...that geyser of blood emanating from my chest is proof I have high blood pressure.'

'Unfortunately, his spine is now clearly visible from the front.'

Fallout   

This post is a demonstration of Dark Forest: Reborn combat system. Our system is unique and provides user with the 'do whatever you want and still get game reaction' experience. 

The world of Dark Forest: Reborn is cruel. You will face local conflicts with highwaymen, clashes of criminal groups and even war. Every event in the game tests your abilities. Will you be able to stay Human?

Let us pretend that misterious forces took your poor body and placed it on the battlefield. Your forces are carving towards the centre of enemy army through the infinite waves of mad savages. They surge forward and it seems their strength is infinite. Your rusty sword is the only weapon you have.

John had only one choice

What will you do? 

- You can try to run away.

- You can join friendly forces in their attack.

- You can try to hide.

- You can cry and ask for help.
- You can just wait and do nothing.

- ...

Every choice will give you additional choices. Your main task is to survive, but it is a really difficult task in the world where your allies are dead and the battle is lost. Let's try to help?

As you can see, you have freedom. Do you want to hit his head using your sword? No problem. His arm? Left or right leg? Yes! If you are strong enough, you can even finish him with a single fatal blow. 

Not enough strength? Try to use words or even so called 'green magic', a gift from high-tech civilization.

You should be fast. The world of Dark Forest: Reborn is a living world - your opponent will not wait for your actions and words, he will keep fighting and hitting you until your death.

Will you be able to protect your allies? Will you save your friends, or maybe your decision will be to kill yet another enemy general? Your glory is important as well: if you show yourself as a good warrior, you will gain reputation that will help you in future adventures.

You should understand your strong and weak skills and abilities. Plan your actions. Don't use everything you have on weak enemies. Save something special for their bosses!

Your energy and time are limited resources. Sometimes it's a really good idea to try to find your opponent's weak spots first.

More details about our combat system will be revealed soon. We're also going to discuss other ways of solving your problems in Dark Forest: Reborn. Smashing everything to pieces is fun, but sometimes you don't want or just can't do such things.

Teaser of an upcoming Dark Forest: Reborn saturday announcement

Dark Forest: Reborn contains a lot of unusual and cool features that you won't find in any text-based game.

Here is the subset of our special strings for an upcoming Saturday announcement that will feature yet another unique game mechanics of Dark Forest: Reborn:

- This is your fatal mistake.
- Die, human fool!
- Your heart is mine!
- Blood! Your blood? Mine blood!
- Enjoy the last few seconds of your life...
- Blood and oblivion!
- I will loot your pathetic corpse!
- This is green magic! You can't!
- I can't see! You coward!
- My face! My eyes! Why!?
- Where are you? Help me! Help!

Basic set contains up to 1000 lines of text, and it's only the beginning.

// Subset given above is also an easter egg for those who love post apocalyptic games ;)

Laid Off from the Synesthesia Factory short review

I played hundreds of IF games and actually have something to say about every single one. Of course, you don't need too read every single trash texts that come out of my mind, so I am trying to post here only the most interesting reviews and funny examples I found.

My main focus during the analysis is gameplay, as always.

The fun fact about Laid Off from the Synesthesia Factory is that you can 'play' it without actually doing anything. Just take a look: (blue text is for input words that I type, green is an output of the game)

[Enter an individual word, a short phrase, or a command.]

> Hell

Your first thought: to check your computer. This is in fact your default thought; give it five years and it'll have your cortex and also your amygdala. "Thought" is the wrong word.  Something closer: anymore, your core creature drive.

The original creature drives: hunger, exhaustion, libido. And their modern replacements: refreshing, unplugging, FOMO.

Spoiler: it will display the same text for almost every input string.

[Enter an individual word, a short phrase, or a command.]

> Tomato

Your next thought: How you have managed such disarray in a week's span. You feel as if you have been dropped into a spot-the-difference picture, the kind from a children's whodunnit book, where you are expected to solve the mystery of how you murdered your life.

It didn't even display a typical 'can't parse this shit' error message. So, actually you will not even understand, is a response of this 'game' is a result of your input replics analysis, or is it just a flow of author's mind flying into your face.

> Super Tomato

Proverb from a dubious online repository: I'm A-OK; I dress au fait; I don't stay home like sad Henri.

Statements that apply to you: zero. Optimism: You could make the second apply right now. And the third will come in half an hour. And even the first, if tonight goes well.

> You are shrimp

You consider PR. The problem: to succeed in doing PR for others you must first prove you've succeeded in doing PR for yourself. You must turn all the glop that is you into a tantalizing direct-to-consumer product, call it Aspirational You. Aspirational You is something special. Aspirational You does not evaporate or sweat under heat; she solidifies, like a cake. If she were knifed the blade would come out clean.

Well, seems shrimp is a good nickname for PR folks. Did game manage to understand me? Or maybe it's parser failed? I have no idea.

I entered the word 'Tomato' ten times or so and the game calmly displayed it's content.

Of course I can play as a smart player, writing only things I notice in the game's output and it will probably give me some results, I can also read the instructions...but I don't want to do it. Regular player won't read any instructions. Regular player doesn't care - he/she sees an input field and starts typing immediately expecting good gameplay.

This is a really good demonstration of serious problem in game development. This kind of problem appears when your game pretends that it is smarter than it is. And there is nothing worse in gamedev than failed expectations of a player. To be an author of such game is like to be an unsuccessful magician.

// P. S. After my first attempt I read the rules and followed them. Game appeared to be quite good. It's writing deserves an additional prize.

Notepad++ custom syntax highlighting tutorial (ChoiceScript example)

I recently noticed that it's not such a rare case when writers of IF (I mean writers, not software developers) use tools like ChoiceScript that have no decent (free) text editors. Those guys can produce 50000+ words per game and it's a pain for them to debug tons of pseudocode without any help from their text editors, even without such simple things like syntax highlighting. 

When I have no time to search for special software for editing texts or code, I use Notepad++.

This tutorial contains two parts:

1.) The first part in which you will just download and install my own style sheet for Notepad++

2.) The second part that will explain you how to create your own style. This part is based on the first one.

You can choose your way of completing this quest ;)

So, let's get started.

1.) Easy way.

1.1.) Download my style file.

1.2.) Open Notepad++ and go to 'Language'.

1.3.) Go to 'Define your own language'.

1.4.) Press 'Import...' button and choose my style file that you downloaded on the step 1.1.

1.5.) Go to 'Keywords List'

1.6.) If everything is okay, you will see something like this:

If everything is not okay...well, unlucky! Try to use the way of pros in the part 2 of this tutorial.

1.7.) Save installed style sheet (I used name 'test123').

1.8.) Choose installed stylesheet here.

1.9.) Your files with ChoiceScript code will look like this:

Congrats!

2.) The way of pros.

- Perform step 1.2 from the part 1: Open Notepad++ and go to 'Language' menu

- Perform step 1.3 from the part 1: Go to 'Define your own language'

- Skip step 1.4 and perform step 1.5: Go to 'Keywords List'

You will see this window with empty fields:

Please, refer to the image above for the additional instructions.
You can add as many ChoiceScript keywords as you want. Press 'Styler' buttons to setup keywords colors.

- Save your style sheet: check step 1.7.

- Choose installed stylesheet: step 1.8. That's all!

I hope this mini-guide will help you. If something didn't work, leave a comment!

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.