121 lines
5.6 KiB
Markdown
121 lines
5.6 KiB
Markdown
# Bessere Tests
|
|
**Bessere Tests** is a dead simple and easy to setup unit testing system for Godot 4.
|
|
|
|
## Index
|
|
- [Why](#why)
|
|
- [Installation](#installation)
|
|
- [Writing tests](#writing-tests)
|
|
- [Configuring](#configuring)
|
|
- [Command line](#command-line)
|
|
- [File structure](#file-structure)
|
|
|
|
## 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:
|
|
```bash
|
|
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:
|
|
```gdscript
|
|
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
|
|
# You can use `ok(message)`, `warn(message)`, `error(message)` or `skip(message)` to set your test result.
|
|
ok("Hello Test!")
|
|
|
|
# You can create multiple tests btw.
|
|
func test_proprietary_blob() -> void:
|
|
error("Not open source.")
|
|
|
|
# Some unimplemented test
|
|
func test_unimplemented() -> void:
|
|
skip()
|
|
```
|
|
|
|
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:
|
|
```gdscript
|
|
extends Node
|
|
|
|
# What directory should tests be located in?
|
|
var test_directory: String = "res://tests"
|
|
# If Bessere Tests should complain about orphan nodes.
|
|
# This behaviour is reportedly broken and does not work correctly (see #1).
|
|
# Rely on Godot's debug/verbose output for this instead (use Bessere Tests' command line script).
|
|
var print_orphan_nodes: bool = false
|
|
```
|
|
|
|
This is the default configuration. If you want to keep a config key to it's default simply comment it out.
|
|
|
|
## Command line
|
|
Use this command to test your project in the command line:
|
|
```bash
|
|
/bin/to/godot.binary --headless -d -v -s --path "." addons/besseretests/src/cmd.gd
|
|
# │ │ │ │ │ │ └───────── Path to Bessere Tests' command line script
|
|
# │ │ │ │ └──────┴──────────── Tells Godot where your project is located
|
|
# │ │ │ └───────────────────── Tells Godot to operate in script mode
|
|
# │ │ └─────────────────────── Makes the output verbose, omit if it prints too much irrelevant output
|
|
# │ └───────────────────────── Starts the engine in debug mode, helps debugging issues in your tests
|
|
# └─────────────────────────────────── Tells Godot to not display a window. Omit if you strictly need a window.
|
|
```
|
|
|
|
The process will exit with code `0` on success (all tests except skipped onces passing), `1` with warnings (all tests either passing or throwing warnings except skipped ones) and `2` on failure (some tests failing).
|
|
|
|
## File structure
|
|
Here's a file structure for this project:
|
|
```plain
|
|
.
|
|
├── 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
|
|
```
|