BessereTests/README.md
2024-03-28 05:37:29 +01:00

4.2 KiB

Bessere Tests

Bessere Tests is a dead simple but easy to setup unit testing system for Godot 4.

Index

Why?

Why this exist you might ask? Well...:

  • Gut 9 doesn't seem to support using get_tree() at all
  • every other unit testing plugin is too simple or complicated
  • we wanted to write our own

Installation

To install BessereTests execute this in your project root:

mkdir -p submodules addons  # Create 'submodules' and 'addons' folders
cd submodules
touch .gdignore  # Make Godot ignore the 'submodules' directory

# Now choose what you want to do:
# -> Cloning (use if you don't use git (yet))
git clone https://git.staropensource.de/StarOpenSource/BessereTests.git besseretests
# -> Using submodules (use if you have a git repository set up)
# git submodule update --init --recursive
# git submodule add https://git.staropensource.de/StarOpenSource/BessereTests.git besseretests


cd ../addons
ln -s ../submodules/besseretests/addons/besseretests .  # Symlink 'submodules/besseretests/addons/besseretests' to 'addons/besseretools'

Now simply activate the plugin in your project settings. To run tests, simply click the Run tests button in the upper-left corner of your main editor window.

Writing tests

First of all create a directory at res://tests (default path, is customizable). Then create a GDScript file, we'll name it readme_example.gd. Now open your script and replace the contents with this:

extends BessereTestsTest

# You can name this whatever you want as long as the function is prefixed with 'test_'.
# If not, it will not be run.
func test_example() -> void:
  # Logging examples
	ldiag("DIAGNOSTIC MESSAGE")
	lverb("VERBOSE MESSAGE")
	linfo("INFORMATIONAL MESSAGE")
	lwarn("WARNING MESSAGE")
	lerror("ERROR MESSAGE")
	#await lcrash("Something horrible happened")  # Must be awaited, uncomment for a little nuke
	
	# Test result (must be set or Bessere Tests will complain)
	# -> Test status
	#    Can be either 0 (ok), 1 (warn), 2 (error) or 3 (skip). Any other value will be marked as invalid.
	test_status = 0
	# -> Test message
	#    Can be set to any string you like, or can be unset.
	#    Would of course be useful to leave a message when 'test_status' is set to anything but 0.
	test_message = "Hello Test!"

# You can create multiple tests btw.
func test_proprietary_blob() -> void:
  test_status = 2
  test_message = "Not open source."

# Some unimplemented test
func test_unimplemented() -> void:
  test_status = 3
  test_message = "TODO"

Use this example to build your tests. And remember: You can have multiple test files (we call them "test suites" or "suites" for short).

Configuring

If you want to update Bessere Tests's configuration create a GDScript file at res://addons/besseretests_config.gd and paste this in:

extends Node

# What directory should tests be located in?
var test_directory: String = "res://tests"

This is the default configuration. If you want to keep a config key to it's default simply comment it out.

File structure

Here's a file structure for this project:

.
├── addons
│   ├── besseretests
│   │   ├── examples                 Example tests used during development
│   │   │   ├── example_test.gd      Contains many tests
│   │   │   └── showcase_logging.gd  Simply tests the logger functionality
│   │   ├── plugin.cfg
│   │   ├── plugin.gd                Plugin enable/disable logic
│   │   ├── scenesrc
│   │   │   ├── editorbutton.tscn
│   │   │   └── runtimescene.tscn
│   │   └── src
│   │       ├── editorbutton.gd      The run scene button but it points to 'res://addons/besseretests/scenesrc/runtimescene.tscn'
│   │       ├── runtimescene.gd      Where the real magic happens, executed after clicking on 'Run tests'
│   │       └── testclass.gd         The 'BessereTestsTest' class
│   └── besseretests_config.gd       Configuration file for development
├── LICENSE
├── project.godot
└── README.md