Gunit Test Framework

The Defoldmine
1

Gunit-hero
Gunit-hero1920×533 98.1 KB

Gunit is a unit testing framework for games.

While the framework does include some classic unit testing facilities similar to what you can find most test frameworks like XUnit or JUnit, the main feature is asynchronous unit tests that can run in the game loop and drive the game the same way that a player does. A few years ago I would’ve emphatically exclaimed: “NO! That’s not a unit test. That sounds like an integration test or an end-to-end test…”.

However, I have since learnt that the “unit” does not necessarily have to be the smallest bit of code that can be tested in isolation, like a class or a function. In fact, I now believe that testing like that is a bad pattern: it couples your tests very directly to your implementation, which means the moment you want to refactor that implementation the tests become wrong and you end up either having to delete them or spend hours trying to adjust them. By using a coarser unit test scope you focus your test more on the requirements you are trying to implement and less on the current implementation, making it easier to refactor in future.

I’ve spent most of the last few weeks getting this into a basic working state, now it is time to release and see if this works in some real game development projects. Hope you find it useful.

Happy testing!

Overview

Gunit GitLab: https://gitlab.com/mattpwest/gunit-defold
Gunit Docs: https://gitlab.com/mattpwest/gunit-defold/-/tree/master/docs

The best way to see some tests in action is to clone the repository, open it in Defold and run it, you’ll see the tests run before the example game becomes playable.

Example of use

Here is a quick demo of what running the tests looks like:

For details on how to integrate this into your game please read the README and the docs.

Example CICD Pipeline

You can look at Gunit’s .gitlab-ci.yml for a simple example of running the tests in pipeline before building the game for Windows and Linux.

14 Likes
2

Gunit Defold 0.2.0 Release

The new version 0.2.0 is available!

To start using it, simply add this to your project dependencies:

https://gitlab.com/mattpwest/gunit-defold/-/archive/0.2.0/gunit-defold-0.2.0.zip

Changes

Improved error location reporting. Now reports failures on the line in the test where an assertion is made, rather than where the assertion is implemented in the library.

Additional assertions:

  • tableEquals
  • tableNotEquals
  • isNil
  • greaterThan
  • greaterThanOrEqual
  • lessThan
  • lessThanOrEqual

Bugfix: contains assertion now escapes magic characters, so assertions should now pass even if the text contains one or more of the magic characters.

7 Likes
3

Gunit Defold 0.3.0 Release

The new version 0.3.0 is available!

To start using it, simply add this to your project dependencies:

https://gitlab.com/mattpwest/gunit-defold/-/archive/0.3.0/gunit-defold-0.3.0.zip

Changes

Feature: added type checks in assertion messages.

  • This fixes a lot of cases where you would get an error inside the GUnit assertion code and be left with no idea where in your test something is failing…

Feature: async test recording (desktop only)

  • You can use the built-in Defold recording feature to record screen captures of async tests (configured per Fixture, check the first page of the manual)
  • Only works on your desktop, not in pipeline…

Fix: mouse click position calculation for non-1920x1080 resolutions. Uses the new camera.screen_xy_to_world(x, y) function. This does mean you now require a camera in your main scene (see gunit/example_main.collection).

Upgrade: Defold version 1.12.0

5 Likes
4

The new version 0.4.0 is available!

To start using it, simply add this to your project dependencies:

https://gitlab.com/mattpwest/gunit-defold/-/archive/0.4.0/gunit-defold-0.4.0.zip

Changes

Feature: added hasError assertion

  • Evaluates the provided function call to see if it throws an error

Feature: added hasErrorLike assertion

  • Evaluates the provided function call to see if it throws an error and checks if its error message contains the specified string

Feature: added hasNoError assertion

  • Evaluates the provided function call to check that it throws no error

Upgrade: Defold version 1.12.2

Notes

Although the pipeline hasn’t passed, this should work fine. I’ve been having flakiness problems in pipeline with some of the complex integration tests that simulate user input, specifically these are refusing to all pass together tonight:

  • Collection_under_test_increments_logo_counter_when_a_logo_is_spawned
  • Collection_under_test_spawns_logo_at_double_size_and_then_animates_them_to_normal_size
  • Collection_under_test_rate_limits_logo_spawns

I can assure you these types of tests work perfectly fine running in Defold on desktop, it just seems to be an issue running under dmengine_headless in pipeline that I can’t pin down…

5 Likes