Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
### Added
- Minecraft 26.3 in `minecraft-versions.json`, so the `Build` workflow's API check and the release boot check cover it; the README and user guide list it (#25).
- `USER_GUIDE.md` and `COMMANDS.md` now say that `/flycommand:fly` works like `/fly` and reaches FlyCommand even when another plugin provides `/fly`.
- Tests that fail the build when the docs' version lists, `/fly` messages or `FlyCommand.fly` permission details disagree with `minecraft-versions.json`, `Main.java` or `plugin.yml`.

### Fixed
- `COMMANDS.md` now lists the exact messages `/fly` shows, including the permission-denied and console alerts, which the 1.0.0 entry below said it already did.
Expand Down
4 changes: 2 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -48,7 +48,7 @@ Please open a bug report [here](https://github.com/Dans-Plugins/FlyCommand/issue

## Testing

`mvn clean package` compiles the plugin and runs its test suite. The suite reads the `plugin.yml` packed into the jar with Bukkit's `PluginDescriptionFile`, the parser a server uses, and checks that `main` names the plugin class, that the build filled in the version, that the name and `api-version` are `FlyCommand` and `1.13`, and that the `Fly` command is declared. The `op` default of the `FlyCommand.fly` permission is read as plain YAML instead, because that parser needs a running server to build a permission. The suite also runs the `/fly` handler against stand-in senders, checking the toggle and its confirmations (including when the command is typed as `/flycommand:fly`), the permission-denied alert, and the console alert. The [Build](.github/workflows/build.yml) workflow runs the same command on every push to `main` and every pull request against it, then the Bukkit API check described under [Supported Minecraft Versions](#supported-minecraft-versions), which `mvn clean package` does not run.
`mvn clean package` compiles the plugin and runs its test suite. The suite reads the `plugin.yml` the build has prepared for the jar with Bukkit's `PluginDescriptionFile`, the parser a server uses, and checks that `main` names the plugin class, that the build filled in the version, that the name and `api-version` are `FlyCommand` and `1.13`, and that the `Fly` command is declared. The `op` default of the `FlyCommand.fly` permission is read as plain YAML instead, because that parser needs a running server to build a permission. The suite also runs the `/fly` handler against stand-in senders, checking the toggle and its confirmations (including when the command is typed as `/flycommand:fly`), the permission-denied alert, and the console alert. Finally, it compares the docs with what they copy: the version lists here and in the [User Guide](USER_GUIDE.md) must match `minecraft-versions.json`, every message in `Main.java` must be quoted in this file, the user guide and the [Commands Reference](COMMANDS.md), and the permission `Main.java` checks must appear in the user guide's table with its `plugin.yml` default, and in the Commands Reference and the [Configuration Guide](CONFIG.md). The [Build](.github/workflows/build.yml) workflow runs the same command on every push to `main` and every pull request against it, then the Bukkit API check described under [Supported Minecraft Versions](#supported-minecraft-versions), which `mvn clean package` does not run.

The tests do not start a server, so the plugin loading and `/fly` being registered are still verified by hand on a Spigot or Paper server, as described under [Manual Validation](#manual-validation-on-a-test-server).

Expand All @@ -60,7 +60,7 @@ The plugin is a single class, built with Maven.

- `src/main/java/me/Daniel/FlyCommand/Main.java` – the whole plugin
- `src/main/resources/plugin.yml` – the plugin manifest, whose `main` value must stay equal to the package and class name of that file; its `version` is filled in from `pom.xml` at build time
- `src/test/java/` – tests of the packaged manifest and of the `/fly` handler
- `src/test/java/` – tests of the packaged manifest, of the `/fly` handler, and of the docs against their sources

### Building

Expand Down
80 changes: 80 additions & 0 deletions src/test/java/me/Daniel/FlyCommand/DocumentationTest.java
Original file line number Diff line number Diff line change
@@ -0,0 +1,80 @@
package me.Daniel.FlyCommand;

import org.bukkit.configuration.file.YamlConfiguration;
import org.junit.jupiter.api.Test;

import java.io.File;
import java.io.IOException;
import java.nio.charset.StandardCharsets;
import java.nio.file.Files;
import java.nio.file.Paths;
import java.util.ArrayList;
import java.util.List;
import java.util.regex.Matcher;
import java.util.regex.Pattern;

import static org.junit.jupiter.api.Assertions.*;

/**
* Reads the Markdown docs next to the files they copy from, so that a version,
* message or permission changed in one place fails the build until the docs
* agree. The strings are taken from the sources, not repeated here, so these
* tests do not need editing when a message changes.
*/
class DocumentationTest {

private static final String SOURCE = "src/main/java/me/Daniel/FlyCommand/Main.java";

private static String read(String path) throws IOException {
return new String(Files.readAllBytes(Paths.get(path)), StandardCharsets.UTF_8);
}

/** The first group of every match, failing if there are none so a stale pattern cannot pass by finding nothing. */
private static List<String> matches(String pattern, String text) {
List<String> found = new ArrayList<>();
Matcher matcher = Pattern.compile(pattern).matcher(text);
while (matcher.find()) {
found.add(matcher.group(1));
}
assertFalse(found.isEmpty(), "nothing matched " + pattern);
return found;
}

@Test
void versionListsMatchMinecraftVersionsJson() throws Exception {
// JSON is valid YAML, so Bukkit's YAML loader reads this file too.
List<String> supported = YamlConfiguration.loadConfiguration(new File("minecraft-versions.json"))
.getStringList("supported");
assertFalse(supported.isEmpty(), "minecraft-versions.json lists no versions");

for (String doc : new String[] { "README.md", "USER_GUIDE.md" }) {
List<String> lists = matches("currently ((?:\\*\\*[^*]+\\*\\*(?:, | and )?)+)", read(doc));
assertEquals(1, lists.size(), doc);
assertEquals(supported, matches("\\*\\*([^*]+)\\*\\*", lists.get(0)), doc);
}
}

@Test
void docsQuoteEveryMessageTheCommandSends() throws Exception {
List<String> messages = matches("sendMessage\\(\"([^\"]+)\"\\)", read(SOURCE));

for (String doc : new String[] { "COMMANDS.md", "USER_GUIDE.md", "README.md" }) {
String text = read(doc);
for (String message : messages) {
assertTrue(text.contains("`" + message + "`"), doc + " does not quote: " + message);
}
}
}

@Test
void docsNameEveryPermissionTheCommandChecks() throws Exception {
YamlConfiguration manifest = YamlConfiguration.loadConfiguration(new File("src/main/resources/plugin.yml"));

for (String permission : matches("hasPermission\\(\"([^\"]+)\"\\)", read(SOURCE))) {
String row = "| `" + permission + "` | `" + manifest.getString("permissions." + permission + ".default") + "` |";
assertTrue(read("USER_GUIDE.md").contains(row), "USER_GUIDE.md has no row: " + row);
assertTrue(read("COMMANDS.md").contains("| `/fly` | `" + permission + "` |"), "COMMANDS.md: " + permission);
assertTrue(read("CONFIG.md").contains("`" + permission + "`"), "CONFIG.md: " + permission);
}
}
}
Loading