BessereTests/README.md

# 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

# Enables development mode. Please keep that disabled.
var dev: bool = false
# What directory should tests be located in?
var test_directory: String = "res://tests"
# The minimum log level.
# Possible values: 0 = diagnostic, 1 = verbose, 2 = informational, 3 = warning, 4 = error
var log_level: int = 2
# The logging template. Is of type String.
# Available placeholders: %time%, %time_us%, %time_ms%, %level%, %origin%, %message%, %color_start% & %color_end%
var log_format = null
# 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
```