Add docs for the test toolkit

CommandAPI · JorelAli · Dec 4, 2024 · Oct 28, 2024 · Jul 4, 2024 · Jul 5, 2024
commit 2ab0c177b552d964c73e86ec7b45354deebfef35
diff --git a/commandapi-documentation-code/pom.xml b/commandapi-documentation-code/pom.xml
@@ -48,7 +48,6 @@
 			<groupId>net.kyori</groupId>
 			<artifactId>adventure-platform-bukkit</artifactId>
 			<version>4.2.0</version>
-			<scope>test</scope>
 		</dependency>
 		<dependency>
 			<groupId>io.papermc.paper</groupId>
@@ -69,6 +68,23 @@
 			<version>${project.version}</version>
 		</dependency>
 
+		<!-- Testing examples dependencies -->
+		<dependency>
+			<groupId>com.github.seeseemelk</groupId>
+			<artifactId>MockBukkit-v1.20</artifactId>
+			<version>3.9.0</version>
+		</dependency>
+		<dependency>
+			<groupId>dev.jorel</groupId>
+			<artifactId>commandapi-bukkit-test-toolkit</artifactId>
+			<version>${project.version}</version>
+		</dependency>
+		<dependency>
+			<groupId>org.junit.jupiter</groupId>
+			<artifactId>junit-jupiter-engine</artifactId>
+			<version>5.8.2</version>
+		</dependency>
+
 		<!-- Other -->
 		<dependency>
 			<groupId>de.tr7zw</groupId>

diff --git a/commandapi-documentation-code/src/main/java/dev/jorel/commandapi/examples/java/Examples.java b/commandapi-documentation-code/src/main/java/dev/jorel/commandapi/examples/java/Examples.java
@@ -20,6 +20,8 @@
  * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  *******************************************************************************/
 
+import be.seeseemelk.mockbukkit.MockBukkit;
+import be.seeseemelk.mockbukkit.ServerMock;
 import com.mojang.brigadier.LiteralMessage;
 import com.mojang.brigadier.Message;
 import com.mojang.brigadier.ParseResults;
@@ -74,6 +76,8 @@
 import org.bukkit.scoreboard.Scoreboard;
 import org.bukkit.scoreboard.Team;
 import org.bukkit.util.EulerAngle;
+import org.junit.jupiter.api.AfterEach;
+import org.junit.jupiter.api.BeforeEach;
 
 import java.util.*;
 import java.util.Map.Entry;
@@ -2519,6 +2523,33 @@ void subcommands() {
 /* ANCHOR_END: subcommands4 */
 }
 
+class test {
+class Main extends JavaPlugin {
+
+}
+/* ANCHOR: testLoadMockPlugin1 */
+@BeforeEach
+public void setUp() {
+    // Set up MockBukkit server
+    ServerMock server = MockBukkit.mock();
+
+    // Load the CommandAPI plugin
+    MockCommandAPIPlugin.load(config -> config
+        .missingExecutorImplementationMessage("This command cannot be run by %S")
+    );
+
+    // Load our plugin
+    MockBukkit.load(Main.class);
+}
+
+@AfterEach
+public void tearDown() {
+    // Reset for a clean slate next test
+    MockBukkit.unmock();
+}
+/* ANCHOR_END: testLoadMockPlugin1 */
+}
+
 class tooltips {
 {
 /* ANCHOR: tooltips1 */

diff --git a/docssrc/src/SUMMARY.md b/docssrc/src/SUMMARY.md
@@ -113,6 +113,13 @@
 - [Using the DSL](./kotlindsl.md)
 - [Delegated properties](./delegated_properties.md)
 
+# Testing Framework
+
+- [Testing Commands](./test_intro.md)
+- [Set Up](./test_setup.md)
+- [Loading Test CommandAPI](./test_loadmockplugin.md)
+- [Testing Utilities](./test_utilities.md)
+
 -----
 
 # Velocity

diff --git a/docssrc/src/test_intro.md b/docssrc/src/test_intro.md
@@ -0,0 +1,15 @@
+# Testing Commands
+
+When developing large projects, it is good practice to add automated tests for your code. This section of the documentation describes how to use the `commandapi-bukkit-test-toolkit` dependency along with [MockBukkit](https://github.com/MockBukkit/MockBukkit) and [JUnit](https://junit.org/junit5/) to test the usage of commands registered with the CommandAPI.
+
+For a big-picture view, you can find example projects that include automated tests in the [CommandAPI GitHub repository](https://github.com/JorelAli/CommandAPI/tree/master/examples).
+
+<div class="warning">
+
+**Developer's Note:**
+
+Many methods have not yet been implemented in the test toolkit. Most notably, only [primitive arguments](./argument_primitives.md), [String arguments](./argument_strings.md), [literal arguments](./category_literal_arguments.md), and the [`IntegerRangeArgument`](./argument_range.md) are fully implemented. The [`EntitySelectorArgument`, `PlayerArgument`, and `OfflinePlayerArgument`](./argument_entities.md) should mostly work, though [target selector arguments](https://minecraft.wiki/w/Target_selectors#Target_selector_arguments) (e.g. `@e[type=pig]`) are not yet implemented.
+
+If a test ends up calling a method that has not yet been implemented, an `UnimplementedMethodException` will be thrown, causing the test to fail. If you see an `UnimplementedMethodException`, please tell us about it with a [GitHub Issue](https://github.com/JorelAli/CommandAPI/issues) or a message in the CommandAPI Discord. Pull requests are also always welcome!
+
+</div>
diff --git a/docssrc/src/test_loadmockplugin.md b/docssrc/src/test_loadmockplugin.md
@@ -0,0 +1,33 @@
+# Loading The CommandAPI in Tests
+
+## Plugin Dependency
+
+If your plugin depends on the CommandAPI plugin to load, when running tests you should load the `JavaPlugin` `MockCommandAPIPlugin` before you use MockBukkit to [load your plugin](https://mockbukkit.readthedocs.io/en/latest/first_tests.html#creating-the-test-class). You can either load this class directly with `MockBukkit.load(MockCommandAPIPlugin.class)`, or use one of the static `MockCommandAPIPlugin#load` methods:
+
+```java
+MockCommandAPIPlugin load()
+```
+
+Loads the CommandAPI Plugin in the test environment. Works exactly the same as `MockBukkit.load(MockCommandAPIPlugin.class)`.
+
+```java
+MockCommandAPIPlugin load(Consumer<CommandAPIBukkitConfig> configureSettings)
+```
+
+Loads the CommandAPI Plugin after applying the given consumer. This allows configuring any setting from the [config.yml](./config.md#configuration-settings) using the methods provided by [CommandAPIBukkitConfig](./setup_shading.md#loading).
+
+<div class="example">
+
+### Example - Loading test CommandAPI with settings
+
+To change, for example, the `missing-executor-implementation` message while running tests, you can use the method `CommandAPIBukkitConfig#missingExecutorImplementationMessage` when the `configureSettings` callback is run:
+
+```java
+{{#include ../../commandapi-documentation-code/src/main/java/dev/jorel/commandapi/examples/java/Examples.java:testLoadMockPlugin1}}
+```
+
+</div>
+
+## Shaded Dependency
+
+If your plugin shades the CommandAPI, the CommandAPI will automatically load as usual when you use MockBukkit to load your plugin. Just note that you **must** call `CommandAPI.onDisable()` in your plugin's `onDisable` method in order for the test environment to reset properly after each test.
diff --git a/docssrc/src/test_setup.md b/docssrc/src/test_setup.md
@@ -0,0 +1,89 @@
+# Setting up your project
+
+In the most common simple case, tests can be added directly next to plugin code. Code that goes in your final jar file is located in the `/src/main/` directory, while tests go in `/src/test/`. You can find more information about setting up your project for tests in the [JUnit](https://junit.org/junit5/docs/current/user-guide/#overview-getting-started-example-projects) documentation.
+
+## Dependencies
+
+When you add the dependencies for MockBukkit and `commandapi-bukkit-test-toolkit`, make sure to place them before your main dependencies for the CommandAPI and Spigot/Paper API. This ensures that certain classes that are compatible with the testing environment override the regular classes when running tests.
+
+<div class="multi-pre">
+
+```xml,Plugin_Dependency
+<dependencies>
+    <dependency>
+        <groupId>com.github.seeseemelk</groupId>
+        <artifactId>MockBukkit-v1.20</artifactId>
+        <version>3.9.0</version>
+        <scope>test</scope>
+    </dependency>
+
+    <dependency>
+        <groupId>dev.jorel</groupId>
+        <artifactId>commandapi-bukkit-test-toolkit</artifactId>
+        <version>9.6.0-SNAPSHOT</version>
+        <scope>test</scope>
+    </dependency>
+
+    <dependency>
+        <groupId>dev.jorel</groupId>
+        <artifactId>commandapi-bukkit-core</artifactId>
+        <version>9.6.0-SNAPSHOT</version>
+        <scope>provided</scope>
+    </dependency>
+
+    <dependency>
+        <groupId>org.spigotmc</groupId>
+        <artifactId>spigot-api</artifactId>
+        <version>1.20.6-R0.1-SNAPSHOT</version>
+        <scope>provided</scope>
+    </dependency>
+
+    <dependency>
+        <groupId>org.junit.jupiter</groupId>
+        <artifactId>junit-jupiter-engine</artifactId>
+        <version>5.8.2</version>
+        <scope>test</scope>
+    </dependency>
+</dependencies>
+```
+
+```xml,Shading_CommandAPI
+<dependencies>
+    <dependency>
+        <groupId>com.github.seeseemelk</groupId>
        <artifactId>MockBukkit-v1.20</artifactId>
+        <version>3.9.0</version>
+        <scope>test</scope>
+    </dependency>
+
+    <dependency>
+        <groupId>dev.jorel</groupId>
+        <artifactId>commandapi-bukkit-test-toolkit</artifactId>
+        <version>9.6.0-SNAPSHOT</version>
+        <scope>test</scope>
+    </dependency>
+
+    <dependency>
+        <groupId>dev.jorel</groupId>
+        <artifactId>commandapi-bukkit-shade</artifactId>
+        <version>9.6.0-SNAPSHOT</version>
+        <scope>compile</scope>
+    </dependency>
+
+    <dependency>
+        <groupId>org.spigotmc</groupId>
+        <artifactId>spigot-api</artifactId>
+        <version>1.20.6-R0.1-SNAPSHOT</version>
+        <scope>provided</scope>
+    </dependency>
+
+    <dependency>
+        <groupId>org.junit.jupiter</groupId>
+        <artifactId>junit-jupiter-engine</artifactId>
+        <version>5.8.2</version>
+        <scope>test</scope>
+    </dependency>
+</dependencies>
+```
+
+</div>
diff --git a/docssrc/src/test_utilities.md b/docssrc/src/test_utilities.md
@@ -0,0 +1,108 @@
+# Testing Utilities
+
+The class `CommandAPITestUtilities` provides many static methods to interact with commands registered in the test environment. The standard way to access these methods is by using the class name.
+
+```java
+import dev.jorel.commandapi.CommandAPITestUtilities;
+
+class Tests {
+    @Test
+    void test() {
+        CommandAPITestUtilities.assertCommandSucceeds(...);
+    }
+}
+```
+
+However, you can also call these methods with just the method name if you add a static import:
+
+```java
+import static dev.jorel.commandapi.CommandAPITestUtilities.assertCommandSucceeds;
+
+class Tests {
+    @Test
+    void test() {
+        assertCommandSucceeds(...);
+    }
+}
+```
+
+or make your test class extend `CommandAPITestUtilities`:
+
+```java
+import dev.jorel.commandapi.CommandAPITestUtilities;
+
+class Tests extends CommandAPITestUtilties {
+    @Test
+    void test() {
+        assertCommandSucceeds(...);
+    }
+}
+```
+
+This is similar to importing static methods from the [`org.junit.jupiter.api.Assertions`](https://junit.org/junit5/docs/current/user-guide/#writing-tests-assertions) class, and may help make your tests easier to read.
+
+## Running commands
+
+There are 3 methods to test basic command execution:
+
+```java
+void dispatchCommand(CommandSender sender, String command) throws CommandSyntaxException
+void assertCommandSucceeds(CommandSender sender, String command)
+CommandSyntaxException assertCommandFails(CommandSender sender, String command, String expectedMessage)
+```
+
+`dispatchCommand` will simply attempt to execute a command. It may throw a `CommandSyntaxException` if the command fails, either because it wasn't a valid command or because your command executor threw a [`WrapperCommandSyntaxException`](./commandfailures.md#handling-command-failures).
+
+`assertCommandSucceeeds` will run `dispatchCommand` and cause the test to fail if the command fails for any reason.
+
+`assertCommandFails` will run `dispatchCommand` and cause the test to fail if the command does _not_ throw a `CommandSyntaxException`. This method will also fail if the command throws an exception but with a different error message than the `expectedMessage` String. It returns the `CommandSyntaxException` that was caught in case you want to inspect any other features of the exception.
+
+## Verifying arguments
+
+When a command is executed, you may want to assert that the Objects provided as arguments match your expectations. There are 4 basic methods for doing this:
+
+```java
+void assertCommandSucceedsWithArguments(CommandSender sender, String command, Object... argumentsArray)
+void assertCommandSucceedsWithArguments(CommandSender sender, String command, Map<String, Object> argumentsMap)
+
+void assertCommandFailsWithArguments(CommandSender sender, String command, String expectedFailureMessage, Object... argumentsArray)
+void assertCommandFailsWithArguments(CommandSender sender, String command, String expectedFailureMessage, Map<String, Object> argumentsMap)
+```
+
+If you expect the command to succeed, use `assertCommandSucceedsWithArguments`. If you expect the command's executor to throw a [`WrapperCommandSyntaxException`](./commandfailures.md#handling-command-failures), use `assertCommandFailsWithArguments`. You can give these methods either an array or a Map holding all arguments you expect to be present for the command. 
+
+Note that if the command input cannot be parsed, the command will fail, but a CommandAPI executor will never be run. In this case, a CommandAPI executor will have never been run, so `assertCommandFailsWithArguments` will not have any arguments to inspect, and the test will fail. You can only successfully use `assertCommandFails` in this situation.
+
+## Verifying suggestions
+
+### Suggestion texts
+
+There are 4 basic methods that may be used to verify the text of a command's suggestions:
+
+```java
+void assertCommandSuggests(CommandSender sender, String command, String... expectedSuggestions)
+void assertCommandSuggests(CommandSender sender, String command, List<String> expectedSuggestions)
+
+void assertCommandSuggests(CommandSender sender, String command, int startingAt, String... expectedSuggestions)
+void assertCommandSuggests(CommandSender sender, String command, int startingAt, List<String> expectedSuggestions)
+```
+
+You can either provide the expected suggestions as an array or a List. Note that the suggestions will be provided in alphabetical order.
+
+You can optionally provide a `startingAt` index. This is the place in the command String where you expect the first character of the suggestions will be placed.
+
+### Suggestion tooltips
+
+If the suggestions you want to check include [tooltips](./tooltips.md), you may use these 5 methods:
+
+```java
+Suggestion makeTooltip(String text, String tooltip);
+
+void assertCommandSuggestsTooltips(CommandSender sender, String command, Suggestion... expectedSuggestions)
+void assertCommandSuggestsTooltips(CommandSender sender, String command, List<Suggestion> expectedSuggestions)
+
+void assertCommandSuggestsTooltips(CommandSender sender, String command, int startingAt, Suggestion... expectedSuggestions)
+void assertCommandSuggestsTooltips(CommandSender sender, String command, int startingAt, List<Suggestion> expectedSuggestions)
+```
+
+The 4 `assertCommandSuggestsTooltips` methods work the same as the `assertCommandSuggests` methods, but you provide `Suggestion` objects containing both the text and a tooltip. The `makeTooltip` method allows you to easily create these `Suggestion` objects.
diff --git a/update.sh b/update.sh
@@ -13,6 +13,7 @@ sed -i "s/<version>$oldVer<\/version>/<version>$newVer<\/version>/" docssrc/src/
 sed -i "s/<version>$oldVer<\/version>/<version>$newVer<\/version>/" docssrc/src/setup_dev.md
 sed -i "s/<version>$oldVer<\/version>/<version>$newVer<\/version>/" docssrc/src/setup_annotations.md
 sed -i "s/<version>$oldVer<\/version>/<version>$newVer<\/version>/" docssrc/src/kotlinintro.md
+sed -i "s/<version>$oldVer<\/version>/<version>$newVer<\/version>/" docssrc/src/test_setup.md
 
 # Gradle
 sed -i "s/dev\.jorel:commandapi-bukkit-shade:$oldVer/dev\.jorel:commandapi-bukkit-shade:$newVer/" docssrc/src/setup_shading.md