diff --git a/CHANGELOG.md b/CHANGELOG.md index 955d59d..e1b500a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -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. diff --git a/README.md b/README.md index adf8794..d108d0b 100644 --- a/README.md +++ b/README.md @@ -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). @@ -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 diff --git a/src/test/java/me/Daniel/FlyCommand/DocumentationTest.java b/src/test/java/me/Daniel/FlyCommand/DocumentationTest.java new file mode 100644 index 0000000..3b3a7b4 --- /dev/null +++ b/src/test/java/me/Daniel/FlyCommand/DocumentationTest.java @@ -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 matches(String pattern, String text) { + List 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 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 lists = matches("currently ((?:\\*\\*[^*]+\\*\\*(?:, | and )?)+)", read(doc)); + assertEquals(1, lists.size(), doc); + assertEquals(supported, matches("\\*\\*([^*]+)\\*\\*", lists.get(0)), doc); + } + } + + @Test + void docsQuoteEveryMessageTheCommandSends() throws Exception { + List 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); + } + } +}