Skip to content

Commit

Permalink
Godot 4 release prep (#474)
Browse files Browse the repository at this point in the history
* README
* added wiki to repo
* readmes and whatnots
* add .gdigores to wiki dirs
* wiki disclaimer
* readme
  • Loading branch information
bitwes authored Mar 10, 2023
1 parent d1ee2ea commit 878d097
Show file tree
Hide file tree
Showing 39 changed files with 4,199 additions and 135 deletions.
4 changes: 2 additions & 2 deletions CHANGES.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,6 @@ All notable changes to this project will be documented in this file.
This project adheres to [Semantic Versioning](http://semver.org/).

# 9.0.0
9.0.0 is the first version of GUT released for Godot 4. Any version below 9.0.0 is for 3.x. See the Godot 4 README in the `godot_4` branch for changes to GUT from 3.x.
9.0.0 is the first version of GUT released for Godot 4. Any version below 9.0.0 is for 3.x. See the [GODOT_4_README.md](https://github.com/bitwes/Gut/blob/godot_4/GODOT_4_README.md) in the `godot_4` branch for changes to GUT from 3.x.

The wiki has not been updated yet for GUT 9.0.0.
The wiki has not been updated yet for GUT 9.0.0, but it has been moved to the `godot_4` branch so it can be edited via this repo. Changes to the wiki will be pushed to https://bitwes.github.io/GutWiki/Godot4/.
64 changes: 19 additions & 45 deletions GODOT_4_README.md
Original file line number Diff line number Diff line change
@@ -1,60 +1,29 @@
# Porting GUT to Godot 4.0
# GUT has been ported to Godot 4.0
GUT 9.0.0 is the first release to support Godot 4. Going forward two versions will be maintainted until Godot 3.x becomes obsolete. GUT versions >= 9.0.0 will work with Godot 4. GUT versions < 9.0.0 (currently 7.4.2) will work with Godot 3.x.

IT'S MOSTLY USABLE!!
All issues related to the Godot 4 have the [Godot 4.0](https://github.com/bitwes/Gut/issues?q=is%3Aissue+is%3Aopen+label%3A%22Godot+4.0%22) tag.

## Overview
Ported to Godot 4 RC 6
__!! NOTE !!__ The wiki has not yet been updated for GUT 9.0.0 and Godot 4. I need to find a solution for maintaining two wikis first.

GUT is currently mostly usable in 4.0. The panel works for the most part but still has bugs. The CLI and VSCode Plugin work fine.

This file tracks the changes that have occurred in porting GUT to Godot 4.0. All issues related to the conversion have the [Godot 4.0](https://github.com/bitwes/Gut/issues?q=is%3Aissue+is%3Aopen+label%3A%22Godot+4.0%22) tag.


## Contributing
Pull requests are welcome. You can look at the [Godot 4.0](https://github.com/bitwes/Gut/issues?q=is%3Aissue+is%3Aopen+label%3A%22Godot+4.0%22) issues for items that need to be addressed. If you find something that is not mentioned, please make an issue. There are also a lot of pending and failing tests that need to be addressed.

Read the "Working" and "Broken" features section before starting.


## Godot 4 Changes
These are changes to Godot that affect how GUT is used/implemented.
# Godot 4 Changes
These are changes to Godot that affect how GUT is used/implemented. There is more information about these changes and how GUT has been altered below.

* `setget` has been replaced with a completely new syntax. More info at [#380](/../../issues/380). Examples of the new way and the new `assert_property` method below.
* `connect` has been significantly altered. The signal related asserts will likely change to use `Callable` parameters instead of strings. It is possible to use strings, so this may remain in some form. More info in [#383](/../../issues/383).
* `yield` has been replaced with `await`. `yield_to`, `yield_for`, and `yield_frames` have been deprecated, the new methods are `wait_seconds`, `wait_frams` and `wait_for_signal`. There are exampels below and more info at [#382](/../../issues/382).
* Arrays are pass by reference now.
* Dictionaries are compared by value now.
* `File` and `Directory` have been replaced with `FileAccess` and `DirAccess`.
* `is` no longer accepts a variable for a class. You must use `is_instance_of` instead.


## Working Features
* The command line seems to be working fine.
* The in-editor panel is usable, but not bug free yet.
* Most all asserts are working now.
* `assert_is` seems is working now.
* Signal asserts
* Signal connection asserts
* Orphan monitoring
* Doubling, Spying, Stubbing (mostly). Doubling Inner Classes has changed.
* Using `await` (the new `yield`) in tests, and all the GUT supplied `yield_` methods. See notes in Changes section.
* Input mocking.
* Doubling Inner Classes has been fixed and all the tests have been restored.
* Comparing Dictionary/Arrays with `assert_eq`, `assert_eq_deep`, and the new `assert_same` and `assert_not_same` for comparing references. See Godot's new `is_same` function for details on how `assert_same` works (it's just an assertion wrapper around `is_same`). See the section "Comparing Dictionaries and Arrays" below for more details.


## Broken Features
* Gut Panel. The in-editor panel has a lot of bugs, but you can run individual scripts or your entire test suite from the panel.
* Other misc items.



## Changes
### Usage
# What's new/changed in GUT 9.0.0 for Godot 4.0
* Any methods that were deprecated in GUT 7.x have been removed.
* `assert_setget` no longer works (it now just fails with a message). `assert_property` has been altered to work with the new setter/getter syntax. `assert_set_property`, `assert_readonly_property`, and `assert_property_with_backing_variable` have been added.
* To aid refactoring, `assert_property` and `assert_property_with_backing_variable` will warn if any "public accessors" are found for the property ('get_' and 'set_' methods).
* `assert_property` now requires an instance instead of also working with a loaded objects.
* Doubling strategy flags have been renamed to `INCLUDE_SUPER` (was `FULL`) and `SCRIPT_ONLY` (was `PARTIAL`). The default is `SCRIPT_ONLY`. These names may change again before release. I wanted something more descriptive and less likely to be confused with partial doubles.
* Doubling strategy flags have been renamed to `INCLUDE_SUPER` (was `FULL`) and `SCRIPT_ONLY` (was `PARTIAL`). The default is `SCRIPT_ONLY`. I wanted something more descriptive and less likely to be confused with partial doubles.
* Added support for a `skip_script` test-script variable. This can be added to any test-script or inner-class causing GUT to skip running tests in that script. The script will be included in the "risky" count and appear in the summary as skipped. This was done to help porting tests to 4.0 but might stick around as a permanent feature.
```gdscript
var skip_script = 'The reason for skipping. This will be printed in the output.'
Expand All @@ -73,8 +42,10 @@ await wait_frames(30, 'optional message')
```
* Doubling no longer supports paths to a script or scene. Load the script or scene first and pass that to `double`. See the "Doubling Changes" section for more details.
* Doubling Inner Classes now requires you to call `register_inner_classes` first. See the "Doubling Changes" sedtion for more details.
* Comparing Dictionary/Arrays with `assert_eq`, `assert_eq_deep`, and the new `assert_same` and `assert_not_same` for comparing references. See Godot's new `is_same` function for details on how `assert_same` works (it's just an assertion wrapper around `is_same`). See the section "Comparing Dictionaries and Arrays" below for more details.


### Comparing Dictionaries and Arrays
## Comparing Dictionaries and Arrays
In Godot 3.x dictionaries were compared by reference and arrays were compared by value. In 4.0 both are compared by value. Godot 4.0 introduces the `is_same` method which (amongst other things) will compare dictionaries and arrays by reference.

GUT's `assert_eq` and `asssert_ne` changed to match Godot's behavior. To compare by reference you can use the new `assert_same` or `assert_not_same`. This works with arrays and dictionaries. Review Godot's documentation for `is_same`. When comparing dictionaries and arrays it is recommended that you use `assert_eq_deep` since it provides more detailed output than `assert_eq`.
Expand All @@ -87,7 +58,7 @@ The shallow compare functionanlity has been removed since it no longer applies.
Final note: `assert_eq` does not use `assert_eq_deep` since `assert_eq_deep` compares each element of both arrays/dictionaries and provides detailed info about what is different. This can be slow for large arrays/dictionaries. Godot's `==` operator uses a hashing function which is much faster but does not provide information about what is different in each array/dictionary. With `assert_eq`, `assert_eq_deep`, and `assert_same` (and their inverses) you have fine grained control over the type of comparision that is performed.


### Doubling Changes
## Doubling Changes
#### Doubling scripts and scenes
The `double` method no longer supports paths to scripts or scenes. You should `load` the script or scene first, and then pass that to `double` instead.
```
Expand All @@ -99,7 +70,7 @@ If you pass a string then an error message will be printed and `double` will ret
'Invalid call. Nonexistent function 'new' in base 'Nil'.'
```

#### Doubling Inner Classes
### Doubling Inner Classes
The `double` method no longer supports strings for the path of the base script or a string of the name of the Inner Class. You must call `register_inner_classes` then pass the Inner Class to `double`. You only have to do this once, so it is best to call it in `before_all` or a pre-hook script. Registering multiple times does nothing. Failing to call `register_inner_classes` will result in a GUT error and a runtime error.
```gdscript
# Given that SomeScript contains the class InnerClass that you wish to to double:
Expand Down Expand Up @@ -139,12 +110,15 @@ var foo = 10:
```
With this approach you can set `_foo` internally in your class without triggering the `foo_changed` signal. When you see `foo =` anywhere in your code, it will be going through the accessor. When you see `_foo =` you are only setting the backing variable.

To test this new paradigm `assert_setget` has been removed. `assert_property` has changed to work with the new syntax. Added `assert_property_with_backing_variable` to validate the backing variable wiring....etc.
To test this new paradigm `assert_setget` has been removed. `assert_property` has changed to work with the new syntax. `assert_property_with_backing_variable` was added to validate the backing variable wiring. If you use `assert_property_with_backing_variable` it will verify that the proeperty has accessors and will also look for a `_<varname>` variable with the same name and verify it is being set.

`assert_property` will generate a warning when it finds "public" accessors for these properties (`get_foo`, `set_foo`).

# Wiki
The wiki has been copied into the `godot_4` branch and can be edited through this repo. It is hosted at https://bitwes.github.io/GutWiki/Godot4/. Eventually 3.x GUT will get moved there as well.


## Implementation Changes
# Implementation Changes
* The `Gut` control has been removed. Adding a `Gut` node to a scene to run tests will no longer work. This control dates back to Godot 2.x days. With GUT 7.4.1 I believe the in-editor Gut Panel has enough features to discontinue using a Scene/`Gut` control to run tests. Another approach for running tests in a deployed project will be added at some point.
* The GUI for GUT has been simplified to reflect that it is no longer used to run tests, just display progress and output. It has also been decoupled from `gut.gd`. `gut.gd` is now a `Node` instead of a `Control` and all GUI logic has been removed. New signals have been added so that a GUI can be made without `gut.gd` having to know anything about it. As a result, GUT can now be run without a GUI if that ever becomes something we want to do.
* Replaced the old `yield_between_tests` flag with `paint_after`. This property (initially set to .1s) tells GUT how long to wait before it pauses for 1 frame to allow for painting the screen. This value is checked after each test, so longer tests can still cause a delay in the painting of the screen. This has made the painting a little choppier but has cut down the time it takes to run tests (200 simple tests in 20 scripts dropped from 2+ seconds to .5 seconds to run). This feature is settable from the command line, .gutconfig.json, and GutPanel.
Expand Down
84 changes: 0 additions & 84 deletions Godot_4_latest_run.md

This file was deleted.

12 changes: 8 additions & 4 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,15 +1,18 @@
# Gut 9.0.0 (Godot 4)
# Gut 9.0.0 (Godot 4.0)
GUT (Godot Unit Test) is a unit testing framework for the [Godot Engine](https://godotengine.org/). It allows you to write tests for your gdscript in gdscript.

Version 9.0.0 is for Godot 4.0
Versions below 9.0.0 (currently 7.4.1) is for Godot 3.x
Versions below 9.0.0 (currently 7.4.2) are for Godot 3.x

__!! NOTE !!__ The wiki has not yet been updated for GUT 9.0.0 and Godot 4.
__NOTE__ The wiki for this version has moved to https://bitwes.github.io/GutWiki/Godot4/. It has not been fully updated yet. The Wiki source is now [located in the `godot_4` branch](https://github.com/bitwes/Gut/tree/godot_4/wiki) and Pull Requests are encouraged. See Wiki section in [GODOT_4_README.md](https://github.com/bitwes/Gut/blob/godot_4/GODOT_4_README.md) for details.

See the [GODOT_4_README.md](https://github.com/bitwes/Gut/blob/godot_4/GODOT_4_README.md) for information about how things have changed in Godot 4.

### Donate/Shameless Plug

## Donate/Shameless Plug
If you would like to help support GUT check out my game [Country or State](https://www.youtube.com/watch?v=iCAROKgN9xw&t=4s) on [Android](https://play.google.com/store/apps/details?id=com.butchwesley.country_or_state&hl=en_US&gl=US) and [iOS](https://apps.apple.com/us/app/country-or-state/id1504122706). Then, purchase the full version even if you don't like it. Thanks!


# Features
* Godot 4.0
* [Simple install](https://github.com/bitwes/Gut/wiki/Install) via the Asset Library.
Expand All @@ -25,6 +28,7 @@ More info can be found in the [wiki](https://github.com/bitwes/Gut/wiki).

![Panel](https://raw.githubusercontent.com/bitwes/Gut/master/gut_panel.png)


# Getting Started
* [Install](https://github.com/bitwes/Gut/wiki/Install)
* [Quick Start](https://github.com/bitwes/Gut/wiki/Quick-Start)
Expand Down
Empty file added wiki/.gdignore
Empty file.
Loading

0 comments on commit 878d097

Please sign in to comment.