Add assertCommandSucceeds and assertCommandFails methods to Comma…

…ndAPITestUtilities Add DispatchCommandUtilitiesTests to fully test these methods Add CommandTestBase to provide utilities when testing the test toolkit Enable Jacoco code coverage report for `commandapi-test-toolkit` Add some comments
CommandAPI · JorelAli · Dec 4, 2024 · Oct 28, 2024 · Jul 4, 2024 · Jul 5, 2024
commit 9ad579faf6b68f7c325ef5c5a5227d6323320f2c
diff --git a/commandapi-codecov/pom.xml b/commandapi-codecov/pom.xml
@@ -58,6 +58,12 @@
 			<version>${project.version}</version>
 			<scope>test</scope>
 		</dependency>
+		<dependency>
+			<groupId>dev.jorel</groupId>
+			<artifactId>commandapi-bukkit-test-toolkit</artifactId>
+			<version>${project.version}</version>
+			<!-- This should not have the test scope because it contains classes whose coverage we want to analyze -->
+		</dependency>
 
 		<!-- From commandapi-bukkit-nms-dependency-mojang-mapped -->
 

diff --git a/commandapi-platforms/commandapi-bukkit/commandapi-bukkit-test-toolkit/pom.xml b/commandapi-platforms/commandapi-bukkit/commandapi-bukkit-test-toolkit/pom.xml
@@ -90,12 +90,15 @@
 	</dependencies>
 
 	<build>
+		<!-- Fill ${project.version} in plugin.yml -->
 		<resources>
 			<resource>
 				<directory>src/main/resources</directory>
-				<filtering>true</filtering> <!-- Fill ${project.version} in plugin.yml -->
+				<filtering>true</filtering>
 			</resource>
 		</resources>
+
+		<!-- Remove commandapi-core's VersionHandler in favor of ours -->
 		<plugins>
 			<plugin>
 				<groupId>org.apache.maven.plugins</groupId>
@@ -107,7 +110,6 @@
 							<goal>shade</goal>
 						</goals>
 						<configuration>
-							<!-- Remove commandapi-core's VersionHandler in favor of ours -->
 							<filters>
 								<filter>
 									<artifact>dev.jorel:commandapi-core</artifact>
@@ -133,8 +135,37 @@
 				<version>3.3.0</version>
 				<configuration>
 					<trimStackTrace>false</trimStackTrace>
+					<!-- To help with debugging tests, you can specify an include
+					 to limit a build to only run a certain test file. Uncomment
+					 here if you want to do that: -->
+<!--					<includes>-->
+<!--						<include>**/DispatchCommandUtilitiesTests.java</include>-->
+<!--					</includes>-->
 				</configuration>
 			</plugin>
+
+			<!-- Run code coverage report -->
+			<plugin>
+				<groupId>org.jacoco</groupId>
+				<artifactId>jacoco-maven-plugin</artifactId>
+				<executions>
+					<!-- to avoid bugs in some situations -->
+					<execution>
+						<id>default-prepare-agent</id>
+						<goals>
+							<goal>prepare-agent</goal>
+						</goals>
+					</execution>
+					<!-- create report during maven verify phase -->
+					<execution>
+						<id>report</id>
+						<phase>verify</phase>
+						<goals>
+							<goal>report</goal>
+						</goals>
+					</execution>
+				</executions>
+			</plugin>
 		</plugins>
 	</build>
 </project>
diff --git a/...ndapi-bukkit-test-toolkit/src/main/java/dev/jorel/commandapi/CommandAPITestUtilities.java b/...ndapi-bukkit-test-toolkit/src/main/java/dev/jorel/commandapi/CommandAPITestUtilities.java
@@ -1,28 +1,45 @@
 package dev.jorel.commandapi;
 
+import com.google.errorprone.annotations.CanIgnoreReturnValue;
 import com.mojang.brigadier.exceptions.CommandSyntaxException;
 import org.bukkit.command.CommandSender;
+import org.opentest4j.AssertionFailedError;
 
-import static org.junit.jupiter.api.Assertions.fail;
+import java.util.Objects;
+
+import static org.junit.jupiter.api.Assertions.assertDoesNotThrow;
+import static org.junit.jupiter.api.Assertions.assertThrows;
 
 public class CommandAPITestUtilities {
 	public static MockCommandAPIBukkit getCommandAPIPlatform() {
 		return MockCommandAPIBukkit.getInstance();
 	}
 
-	public static void dispatchCommand(CommandSender sender, String command) {
-		try {
-			dispatchThrowableCommand(sender, command);
-		} catch (CommandSyntaxException exception) {
-			fail(
-				"Expected command dispatch to succeed." +
-					" If you expected this to fail, use `dispatchFailableCommand` instead.",
-				exception
-			);
-		}
+	public static void dispatchCommand(CommandSender sender, String command) throws CommandSyntaxException {
+		getCommandAPIPlatform().getBrigadierDispatcher().execute(command, new MockCommandSource(sender));
 	}
 
-	public static void dispatchThrowableCommand(CommandSender sender, String command) throws CommandSyntaxException {
-		getCommandAPIPlatform().getBrigadierDispatcher().execute(command, new MockCommandSource(sender));
+	public static void assertCommandSucceeds(CommandSender sender, String command) {
+		assertDoesNotThrow(
+			() -> dispatchCommand(sender, command),
+			"Expected command dispatch to succeed"
+		);
+	}
+
+	@CanIgnoreReturnValue
+	public static CommandSyntaxException assertCommandFails(CommandSender sender, String command, String expectedMessage) {
+		CommandSyntaxException exception = assertThrows(
+			CommandSyntaxException.class,
+			() -> dispatchCommand(sender, command),
+			"Expected command dispatch to fail"
+		);
+
+		String actualMessage = exception.getMessage();
+		if (!Objects.equals(expectedMessage, actualMessage)) {
+			throw new AssertionFailedError(
+				"Expected command dispatch to fail with message <" + expectedMessage + ">, but got <" + actualMessage + ">"
+			);
+		}
+		return exception;
 	}
 }
diff --git a/...it/commandapi-bukkit-test-toolkit/src/test/java/dev/jorel/commandapi/CommandTestBase.java b/...it/commandapi-bukkit-test-toolkit/src/test/java/dev/jorel/commandapi/CommandTestBase.java
@@ -0,0 +1,38 @@
+package dev.jorel.commandapi;
+
+import be.seeseemelk.mockbukkit.MockBukkit;
+import be.seeseemelk.mockbukkit.ServerMock;
+import com.google.errorprone.annotations.CanIgnoreReturnValue;
+import org.junit.jupiter.api.function.Executable;
+import org.opentest4j.AssertionFailedError;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertThrows;
+
+public abstract class CommandTestBase extends CommandAPITestUtilities {
+	// Setup
+	protected ServerMock server;
+	protected MockCommandAPIPlugin plugin;
+
+	public void setUp() {
+		server = MockBukkit.mock();
+		plugin = MockBukkit.load(MockCommandAPIPlugin.class);
+	}
+
+	public void tearDown() {
+		MockBukkit.unmock();
+	}
+
+	// Additional test utilities
+	@CanIgnoreReturnValue
+	public <T extends Throwable> T assertThrowsWithMessage(Class<T> exceptionClass, Executable executable, String expectedMessage) {
+		T exception = assertThrows(exceptionClass, executable);
+		assertEquals(expectedMessage, exception.getMessage());
+		return exception;
+	}
+
+	@CanIgnoreReturnValue
+	public AssertionFailedError assertAssertionFails(Executable executable, String expectedMessage) {
+		return assertThrowsWithMessage(AssertionFailedError.class, executable, expectedMessage);
+	}
+}
diff --git a/...bukkit-test-toolkit/src/test/java/dev/jorel/commandapi/DispatchCommandUtilitiesTests.java b/...bukkit-test-toolkit/src/test/java/dev/jorel/commandapi/DispatchCommandUtilitiesTests.java
@@ -0,0 +1,75 @@
+package dev.jorel.commandapi;
+
+import be.seeseemelk.mockbukkit.entity.PlayerMock;
+import org.junit.jupiter.api.AfterEach;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+
+/**
+ * Tests for the methods provided by {@link CommandAPITestUtilities} that handle dispatching commands.
+ */
+class DispatchCommandUtilitiesTests extends CommandTestBase {
+	// Setup
+	@BeforeEach
+	public void setUp() {
+		super.setUp();
+
+		new CommandAPICommand("ping")
+			.executes((sender, args) -> {
+				sender.sendMessage("pong!");
+			})
+			.register();
+	}
+
+	@AfterEach
+	public void tearDown() {
+		super.tearDown();
+	}
+
+	// Tests
+	@Test
+	void testAssertCommandSucceeds() {
+		PlayerMock player = server.addPlayer();
+
+		// Successful use of `assertCommandSucceeds`
+		assertCommandSucceeds(player, "ping");
+		player.assertSaid("pong!");
+
+		// Unsuccessful use of `assertCommandSucceeds`
+		assertAssertionFails(
+			() -> assertCommandSucceeds(player, "pong"),
+			"Expected command dispatch to succeed " +
+				"==> Unexpected exception thrown: " +
+				"com.mojang.brigadier.exceptions.CommandSyntaxException: Unknown command at position 0: <--[HERE]"
+		);
+		player.assertNoMoreSaid();
+	}
+
+	@Test
+	void testAssertCommandFails() {
+		PlayerMock player = server.addPlayer();
+
+		// Successful use of `assertCommandFails`
+		assertCommandFails(
+			player, "pong",
+			"Unknown command at position 0: <--[HERE]"
+		);
+
+		// Unsuccessful uses of `assertCommandFails`
+		assertAssertionFails(
+			() -> assertCommandFails(player, "ping", "Wrong command"),
+			// Command actually did not fail
+			"Expected command dispatch to fail ==> " +
+				"Expected com.mojang.brigadier.exceptions.CommandSyntaxException to be thrown, but nothing was thrown."
+		);
+		player.assertSaid("pong!");
+
+		assertAssertionFails(
+			() -> assertCommandFails(player, "pong", "Wrong command"),
+			// Command failed, but not with the given expected message
+			"Expected command dispatch to fail with message <Wrong command>, but got <Unknown command at position 0: <--[HERE]>"
+		);
+
+		player.assertNoMoreSaid();
+	}
+}
diff --git a/...kit-test-toolkit/src/test/java/dev/jorel/commandapi/MockCommandAPIPluginLoadingTests.java b/...kit-test-toolkit/src/test/java/dev/jorel/commandapi/MockCommandAPIPluginLoadingTests.java
@@ -8,7 +8,11 @@
 import static org.junit.jupiter.api.Assertions.assertFalse;
 import static org.junit.jupiter.api.Assertions.assertTrue;
 
+/**
+ * Tests for loading the {@link MockCommandAPIPlugin}.
+ */
 class MockCommandAPIPluginLoadingTests {
+	// Setup
 	@BeforeEach
 	public void setUp() {
 		MockBukkit.mock();
@@ -19,6 +23,7 @@ public void tearDown() {
 		MockBukkit.unmock();
 	}
 
+	// Tests
 	@Test
 	void testMockBukkitLoad() {
 		MockCommandAPIPlugin plugin = MockBukkit.load(MockCommandAPIPlugin.class);

diff --git a/.../bukkit/automated-tests-shaded/src/test/java/io/github/jorelali/PingPongCommandTests.java b/.../bukkit/automated-tests-shaded/src/test/java/io/github/jorelali/PingPongCommandTests.java
@@ -7,7 +7,7 @@
 import org.junit.jupiter.api.BeforeEach;
 import org.junit.jupiter.api.Test;
 
-import static dev.jorel.commandapi.CommandAPITestUtilities.dispatchCommand;
+import static dev.jorel.commandapi.CommandAPITestUtilities.assertCommandSucceeds;
 
 class PingPongCommandTests {
 	private ServerMock server;
@@ -30,7 +30,7 @@ public void tearDown() {
 	void runCommand() {
 		PlayerMock player = server.addPlayer();
 
-		dispatchCommand(player, "ping");
+		assertCommandSucceeds(player, "ping");
 
 		player.assertSaid("pong!");
 		player.assertNoMoreSaid();

diff --git a/examples/bukkit/automated-tests/src/test/java/io/github/jorelali/PingPongCommandTests.java b/examples/bukkit/automated-tests/src/test/java/io/github/jorelali/PingPongCommandTests.java
@@ -8,7 +8,7 @@
 import org.junit.jupiter.api.BeforeEach;
 import org.junit.jupiter.api.Test;
 
-import static dev.jorel.commandapi.CommandAPITestUtilities.dispatchCommand;
+import static dev.jorel.commandapi.CommandAPITestUtilities.assertCommandSucceeds;
 
 class PingPongCommandTests {
 	private ServerMock server;
@@ -34,7 +34,7 @@ public void tearDown() {
 	void runCommand() {
 		PlayerMock player = server.addPlayer();
 
-		dispatchCommand(player, "ping");
+		assertCommandSucceeds(player, "ping");
 
 		player.assertSaid("pong!");
 		player.assertNoMoreSaid();