feat: improve gametest api

revert io config rename
make IngredientSupplier purpose less ambiguous

Author: marcus8448

src/main/java/dev/galacticraft/machinelib/api/block/MachineBlock.java

@@ -312,7 +312,7 @@ public void appendHoverText(ItemStack stack, TooltipContext context, List<Compon
         BlockEntity blockEntity = reader.getBlockEntity(pos);
         if (blockEntity instanceof MachineBlockEntity machine) {
             CompoundTag config = new CompoundTag();
-            config.put(Constant.Nbt.CONFIGURATION, machine.getIoConfig().createTag());
+            config.put(Constant.Nbt.CONFIGURATION, machine.getIOConfig().createTag());
             config.put(Constant.Nbt.SECURITY, machine.getSecurity().createTag());
             config.put(Constant.Nbt.REDSTONE_MODE, machine.getRedstoneMode().createTag());
             BlockItem.setBlockEntityData(stack, blockEntity.getType(), config);

src/main/java/dev/galacticraft/machinelib/api/block/entity/MachineBlockEntity.java

@@ -114,7 +114,7 @@ public abstract class MachineBlockEntity extends BlockEntity implements Extended
      */
     private final MachineType<? extends MachineBlockEntity, ? extends MachineMenu<? extends MachineBlockEntity>> type;
 
-    private final IoConfig configuration;
+    private final IOConfig configuration;
     private final SecuritySettings security;
     private @NotNull RedstoneMode redstone = RedstoneMode.IGNORE;
 
@@ -214,11 +214,11 @@ protected MachineBlockEntity(@NotNull MachineType<? extends MachineBlockEntity,
         this.type = type;
         this.name = name;
 
-        IoFace[] faces = new IoFace[6];
+        IOFace[] faces = new IOFace[6];
         for (int i = 0; i < faces.length; i++) {
-            faces[i] = new InternalIoFace(i);
+            faces[i] = new InternalIOFace(i);
         }
-        this.configuration = new IoConfig(faces);
+        this.configuration = new IOConfig(faces);
         this.security = new InternalSecuritySettings();
 
         this.state = new InternalMachineState();
@@ -347,7 +347,7 @@ public void setRedstoneMode(@NotNull RedstoneMode redstone) {
      * {@return the IO configuration of this machine}
      */
     @Contract(pure = true)
-    public final @NotNull IoConfig getIoConfig() {
+    public final @NotNull IOConfig getIOConfig() {
         return this.configuration;
     }
 
@@ -499,7 +499,7 @@ public boolean isActive() {
     @ApiStatus.Internal
     private @Nullable EnergyStorage getExposedEnergyStorage(@Nullable BlockFace face) {
         if (face == null) return this.energyStorage;
-        return this.getIoConfig().get(face).getExposedEnergyStorage(this.energyStorage);
+        return this.getIOConfig().get(face).getExposedEnergyStorage(this.energyStorage);
     }
 
     /**
@@ -533,7 +533,7 @@ public boolean isActive() {
     @ApiStatus.Internal
     private @Nullable ExposedStorage<Item, ItemVariant> getExposedItemStorage(@Nullable BlockFace face) {
         if (face == null) return this.createExposedItemStorage(ResourceFlow.BOTH);
-        return this.getIoConfig().get(face).getExposedItemStorage(this::createExposedItemStorage);
+        return this.getIOConfig().get(face).getExposedItemStorage(this::createExposedItemStorage);
     }
 
     /**
@@ -576,7 +576,7 @@ protected ExposedStorage<Item, ItemVariant> createExposedItemStorage(ResourceFlo
     @ApiStatus.Internal
     private @Nullable ExposedStorage<Fluid, FluidVariant> getExposedFluidStorage(@Nullable BlockFace face) {
         if (face == null) return this.createExposedFluidStorage(ResourceFlow.BOTH);
-        return this.getIoConfig().get(face).getExposedFluidStorage(this::createExposedFluidStorage);
+        return this.getIOConfig().get(face).getExposedFluidStorage(this::createExposedFluidStorage);
     }
 
     /**
@@ -884,13 +884,13 @@ public void setAccessLevel(@NotNull AccessLevel accessLevel) {
     /**
      * Subclass that tracks modifications to save and re-render the block entity.
      */
-    private class InternalIoFace extends IoFace {
+    private class InternalIOFace extends IOFace {
         private final BlockFace face;
         private @Nullable ExposedStorage<Item, ItemVariant> cachedItemStorage = null;
         private @Nullable ExposedStorage<Fluid, FluidVariant> cachedFluidStorage = null;
         private @Nullable EnergyStorage cachedEnergyStorage = null;
 
-        public InternalIoFace(int i) {
+        public InternalIOFace(int i) {
             super(ResourceType.NONE, ResourceFlow.BOTH);
             this.face = BlockFace.values()[i];
         }

src/main/java/dev/galacticraft/machinelib/api/compat/transfer/ExposedStorage.java

@@ -37,6 +37,7 @@
 
 /**
  * Represents a resource storage exposed to adjacent blocks or items.
+ * Has additional restrictions on the flow of resources compared to {@link ResourceStorage}s.
  *
  * @param <Resource> the type of resource stored in the storage
  * @param <Variant> the type of variant associated with the resource

src/main/java/dev/galacticraft/machinelib/api/gametest/MachineGameTest.java

@@ -160,6 +160,11 @@ public TestFunction createDrainFluidIntoItemTest(int slot, Fluid fluid, int tank
         });
     }
 
+    /**
+     * Creates a machine at the {@link #MACHINE_POS} position.
+     * @param helper the game test helper
+     * @return the newly created machine
+     */
     protected Machine createMachine(GameTestHelper helper) {
         helper.setBlock(MACHINE_POS, this.type.getBlock());
         return (Machine) helper.getBlockEntity(MACHINE_POS);

src/main/java/dev/galacticraft/machinelib/api/gametest/MachineTestContext.java

@@ -30,6 +30,9 @@
 import java.util.ArrayList;
 import java.util.List;
 
+/**
+ * Wrapper around {@link GameTestHelper} with additional methods for testing machines.
+ */
 public class MachineTestContext {
     private final BlockPos pos;
     private final GameTestHelper helper;
@@ -40,6 +43,9 @@ public MachineTestContext(BlockPos pos, GameTestHelper helper) {
         this.helper = helper;
     }
 
+    /**
+     * {@return the game test helper}
+     */
     public GameTestHelper helper() {
         return this.helper;
     }
@@ -54,10 +60,22 @@ public void assertTrue(boolean b, String message) {
         }
     }
 
+    /**
+     * Fails the test with the given message.
+     * @param message the message to fail with
+     * @param objects the objects to format the message with
+     * @return a new {@link GameTestAssertPosException} with the given message
+     */
     public GameTestAssertPosException fail(String message, Object... objects) {
         return new GameTestAssertPosException(new MessageFormat(message).format(objects), this.helper.absolutePos(this.pos), this.pos, this.helper.getTick());
     }
 
+    /**
+     * Fails the test with the given message.
+     *
+     * @param message the message to fail with
+     * @return a new {@link GameTestAssertPosException} with the given message
+     */
     public GameTestAssertPosException fail(String message) {
         return new GameTestAssertPosException(message, this.helper.absolutePos(this.pos), this.pos, this.helper.getTick());
     }

src/main/java/dev/galacticraft/machinelib/api/gametest/RecipeGameTest.java

@@ -84,7 +84,7 @@ protected void fillOutputSlots(@NotNull MachineItemStorage storage) {
 
     protected void fulfillRunConditions(Machine machine) {
         for (IngredientSupplier<C, R, Machine> condition : this.conditions) {
-            condition.fulfillRunRequirements(machine);
+            condition.supplyIngredient(machine);
         }
     }
 
@@ -129,7 +129,7 @@ protected void tryCraftPartial(GameTestHelper helper, int ignored) {
 
         for (int i = 0; i < this.conditions.size(); i++) {
             if (i == ignored) continue;
-            this.conditions.get(i).fulfillRunRequirements(machine);
+            this.conditions.get(i).supplyIngredient(machine);
         }
 
         helper.runAfterDelay(this.recipeRuntime, () -> {

src/main/java/dev/galacticraft/machinelib/api/gametest/SimpleGameTest.java

@@ -61,11 +61,11 @@ public abstract class SimpleGameTest implements FabricGameTest {
                 tests.add(this.createTest(basicTest.batch(), basicTest.group(), method.getName(), basicTest.structure(), basicTest.workTime(), basicTest.setupTime(), helper -> {
                     Runnable runnable = GameTestUtils.invokeUnorderedArguments(this, method, helper);
                     if (runnable == null) {
-                        if (basicTest.workTime() == 1) helper.succeed();
+                        if (basicTest.setupTime() == 1) helper.succeed();
                     } else {
-                        helper.runAfterDelay(1, () -> {
+                        helper.runAfterDelay(basicTest.setupTime(), () -> {
                             runnable.run();
-                            helper.succeed();
+                            if (basicTest.workTime() == 1) helper.succeed();
                         });
                     }
                 }));

src/main/java/dev/galacticraft/machinelib/api/gametest/annotation/BasicTest.java

@@ -23,20 +23,59 @@
 package dev.galacticraft.machinelib.api.gametest.annotation;
 
 import dev.galacticraft.machinelib.api.gametest.SimpleGameTest;
+import net.minecraft.gametest.framework.GameTest;
 
 import java.lang.annotation.ElementType;
 import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
+/**
+ * Creates simple one-step game tests when used in conjunction with {@link SimpleGameTest} (and descendants).
+ *
+ * <p>{@code @BasicTest} annotated methods must not be {@code private} or {@code static}.
+ *
+ * <p>{@code @BasicTest} annotated methods can either take no arguments or a single {@link net.minecraft.gametest.framework.GameTestHelper} argument.
+ *
+ * <p>{@code @BasicTest} annotated methods can return void or a {@link Runnable}.
+ *
+ * <p>If a {@link Runnable} is returned, it will be run after the setup time has passed.
+ * And the test will succeed if the runnable executes without failure and work time is 1.
+ * Otherwise, if setup time is 1, the test will succeed immediately (assuming no failures raised).
+ *
+ * @see GameTest
+ */
 @Target(ElementType.METHOD)
 @Retention(RetentionPolicy.RUNTIME)
 public @interface BasicTest {
+    /**
+     * {@return the batch name of the test}
+     * @see GameTest#batch()
+     */
     String batch();
+
+    /**
+     * {@return the group name of the test}
+     * Used for naming purposes only.
+     */
     String group() default "";
+
+    /**
+     * {@return the structure to use for the test}
+     * Defaults to an empty (all air) 3x3 structure.
+     * @see GameTest#template()
+     */
     String structure() default SimpleGameTest.STRUCTURE_3x3;
 
+    /**
+     * {@return the time to wait before executing the work runnable, or before succeeding if no work runnable is provided}
+     * If the value is greater than one and no runnable is provided, the test must be succeeded manually.
+     */
     int setupTime() default 1;
 
+    /**
+     * {@return the time to wait before succeeding after the work runnable}
+     * If the value is greater than one, the test must be succeeded manually.
+     */
     int workTime() default 1;
 }

src/main/java/dev/galacticraft/machinelib/api/gametest/annotation/MachineTest.java

@@ -22,28 +22,60 @@
 
 package dev.galacticraft.machinelib.api.gametest.annotation;
 
+import dev.galacticraft.machinelib.api.gametest.MachineTestContext;
 import dev.galacticraft.machinelib.api.gametest.SimpleGameTest;
+import net.minecraft.gametest.framework.GameTest;
 
 import java.lang.annotation.ElementType;
 import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
 /**
- * Represents a test that has to wait a specified number of ticks for results.
- * Annotated methods should have initial setup in their body,
- * and return a {@link Runnable} that verifies state at the end.
+ * <p>{@code @MachineTest} annotated methods should only be found in {@link dev.galacticraft.machinelib.api.gametest.MachineGameTest}s and descendants.
+ *
+ * <p>{@code @MachineTest} annotated methods must not be {@code private} or {@code static}.
+ *
+ * <p>{@code @MachineTest} annotated methods can take
+ * a {@link net.minecraft.gametest.framework.GameTestHelper},
+ * a {@link MachineTestContext},
+ * OR a {@link dev.galacticraft.machinelib.api.block.entity.MachineBlockEntity} (and descendant classes).
+ *
+ * <p>{@code @MachineTest} annotated methods should return a {@link Runnable} that will be executed after {@code workTime} ticks have passed.
  */
 @Target(ElementType.METHOD)
 @Retention(RetentionPolicy.RUNTIME)
 public @interface MachineTest {
+    /**
+     * {@return the batch name of the test}
+     * @see GameTest#batch()
+     */
     String batch() default "";
+
+    /**
+     * {@return the group name of the test}
+     * Used for test naming only.
+     */
     String group() default "";
+
+    /**
+     * {@return the structure file to use for the test}
+     * @see GameTest#template()
+     */
     String structure() default SimpleGameTest.STRUCTURE_3x3;
 
+    /**
+     * {@return the setup time of the test}
+     */
     int setupTime() default 1;
 
+    /**
+     * {@return the work time of the test}
+     */
     int workTime() default 1;
 
+    /**
+     * {@return whether to capture {@link net.minecraft.gametest.framework.GameTestAssertException}s and unwrap them.
+     */
     boolean captureAssertions() default true;
 }

src/main/java/dev/galacticraft/machinelib/api/gametest/annotation/TestSuite.java

@@ -27,8 +27,15 @@
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
+/**
+ * Applies default values to all test methods in the class.
+ */
 @Target(ElementType.TYPE)
 @Retention(RetentionPolicy.RUNTIME)
 public @interface TestSuite {
+    /**
+     * {@return the name of the test suite}
+     * Sets the default group name for all test methods in the class.
+     */
     String value(); // name
 }

src/main/java/dev/galacticraft/machinelib/api/gametest/recipe/IngredientSupplier.java

@@ -26,7 +26,18 @@
 import net.minecraft.world.Container;
 import net.minecraft.world.item.crafting.Recipe;
 
+/**
+ * A functional interface for fulfilling the run requirements of a machine.
+ * @param <C> the type of container
+ * @param <R> the type of recipe
+ * @param <Machine> the type of machine
+ */
 @FunctionalInterface
 public interface IngredientSupplier<C extends Container, R extends Recipe<C>, Machine extends RecipeMachineBlockEntity<C, R>> {
-    void fulfillRunRequirements(Machine machine);
+    /**
+     * Fulfills a single run requirement of a machine (energy, item, fluid, etc.).
+     * It is best to split requirements to test as many edge cases as possible.
+     * @param machine the machine to supply an ingredient to
+     */
+    void supplyIngredient(Machine machine);
 }

src/main/java/dev/galacticraft/machinelib/api/machine/MachineRenderData.java

@@ -22,8 +22,15 @@
 
 package dev.galacticraft.machinelib.api.machine;
 
-import dev.galacticraft.machinelib.api.machine.configuration.IoConfig;
+import dev.galacticraft.machinelib.api.machine.configuration.IOConfig;
 
+/**
+ * The data required to render a machine on the client.
+ * By default, no data is synced to the client, so this should be manually synchronized if more data is needed.
+ */
 public interface MachineRenderData {
-    IoConfig getIoConfig();
+    /**
+     * {@return the I/O configuration of the machine}
+     */
+    IOConfig getIOConfig();
 }