Skip to content

Commit e027b7d

Browse files
mstrhakrmstrhakr
committed
Add DocTest Validation Plugin for Unraid
- Initial release of the DocTest validation plugin. - Validates various features including event system, page file rendering, config parsing, $var array access, and notifications. - Implemented event logging for array operations and notifications. - Created validation scripts to check documented events, file paths, PHP functions, and $var array properties. - Added README and default configuration for the plugin. - Included validation results for Unraid version 7.2.3 with detailed pass/fail metrics.
1 parent 7ac045a commit e027b7d

30 files changed

Lines changed: 1268 additions & 0 deletions

‎validation/README.md‎

Lines changed: 113 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,113 @@
1+
# Documentation Validation Suite
2+
3+
This directory contains tools to validate the accuracy of this documentation against live Unraid systems.
4+
5+
## Contents
6+
7+
| File/Directory | Purpose |
8+
|---------------|---------|
9+
| `doctest.plg` | Installable test plugin (requires GitHub release for TXZ) |
10+
| `plugin/` | Plugin source and build scripts |
11+
| `scripts/` | Validation scripts to verify documentation claims |
12+
| `results/` | Test results from validation runs against specific Unraid versions |
13+
14+
## Using the Test Plugin
15+
16+
### Quick Install (after release is published)
17+
18+
```bash
19+
plugin install https://raw.githubusercontent.com/mstrhakr/unraid-plugin-docs/main/validation/doctest.plg
20+
```
21+
22+
### Local Install (for development/testing)
23+
24+
1. Copy the plugin source to your Unraid server:
25+
```bash
26+
scp -r validation/plugin/source root@your-server:/tmp/doctest-build/
27+
```
28+
29+
2. Build the TXZ on the server:
30+
```bash
31+
ssh root@your-server
32+
cd /tmp/doctest-build
33+
mkdir -p build/usr/local/emhttp/plugins/doctest
34+
cp -R source/emhttp/* build/usr/local/emhttp/plugins/doctest/
35+
chmod 755 build/usr/local/emhttp/plugins/doctest/event/*
36+
cd build && tar -cJf ../doctest-2026.02.01.txz .
37+
```
38+
39+
3. Install using the local PLG:
40+
```bash
41+
plugin install /tmp/doctest-build/doctest-local.plg
42+
```
43+
44+
### What It Tests
45+
46+
The `doctest` plugin validates:
47+
48+
- **Event System** - All 16 documented events are logged with timestamps
49+
- **Page Files** - Settings page demonstrates header parsing, PHP integration
50+
- **Configuration** - `parse_plugin_cfg()` function with default values
51+
- **Global Arrays** - Access to `$var` (system state), `$disks` (disk info)
52+
- **Notifications** - Test button for the notification system
53+
- **File Persistence** - Config files in `/boot/config/plugins/` survive reboot
54+
55+
### Plugin UI Location
56+
57+
After installation, go to **Settings → Other Settings → DocTest Validation**
58+
59+
The page shows:
60+
- Plugin configuration using `parse_plugin_cfg()`
61+
- Live `$var` array values (hostname, timezone, version, etc.)
62+
- Disk count and array status
63+
- Event log viewer (shows last 50 events)
64+
- Test button for notifications
65+
66+
### Viewing Results
67+
68+
After installation:
69+
- Navigate to **Settings → DocTest Validation** in the Unraid UI
70+
- Check `/var/log/doctest-events.log` for event logging
71+
- Review syslog: `grep doctest /var/log/syslog`
72+
73+
## Running Validation Scripts
74+
75+
The scripts can be run directly on an Unraid server:
76+
77+
```bash
78+
# Copy scripts to server
79+
scp -r scripts/ root@your-server:/tmp/validation/
80+
81+
# Run all validations
82+
ssh root@your-server "bash /tmp/validation/validate-all.sh"
83+
84+
# Run individual validations
85+
ssh root@your-server "bash /tmp/validation/validate-events.sh"
86+
ssh root@your-server "bash /tmp/validation/validate-paths.sh"
87+
ssh root@your-server "bash /tmp/validation/validate-vars.sh"
88+
```
89+
90+
## Validation Results
91+
92+
Results are stored in `results/` with filenames matching Unraid versions:
93+
94+
- `unraid-7.2.3.md` - Results from Unraid 7.2.3
95+
96+
### Contributing Results
97+
98+
If you run the validation on a different Unraid version:
99+
100+
1. Run `validate-all.sh` on your server
101+
2. Save the output to `results/unraid-X.Y.Z.md`
102+
3. Submit a PR with the new results
103+
104+
## Validation Status
105+
106+
| Component | Last Validated | Unraid Version |
107+
|-----------|---------------|----------------|
108+
| Event System | 2026-02-01 | 7.2.3 |
109+
| File Paths | 2026-02-01 | 7.2.3 |
110+
| $var Array | 2026-02-01 | 7.2.3 |
111+
| Page Files | 2026-02-01 | 7.2.3 |
112+
| PLG Structure | 2026-02-01 | 7.2.3 |
113+
| PHP Functions | 2026-02-01 | 7.2.3 |

‎validation/doctest.plg‎

Lines changed: 79 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
<?xml version='1.0' standalone='yes'?>
2+
<!DOCTYPE PLUGIN [
3+
<!ENTITY name "doctest">
4+
<!ENTITY author "unraid-plugin-docs">
5+
<!ENTITY version "2026.02.01">
6+
<!ENTITY launch "Settings/DocTest">
7+
<!ENTITY pluginURL "https://raw.githubusercontent.com/mstrhakr/unraid-plugin-docs/main/validation/doctest.plg">
8+
<!ENTITY pluginLOC "/boot/config/plugins/&name;">
9+
<!ENTITY emhttpLOC "/usr/local/emhttp/plugins/&name;">
10+
<!ENTITY txzName "doctest-2026.02.01.txz">
11+
<!ENTITY txzURL "https://github.com/mstrhakr/unraid-plugin-docs/releases/download/v2026.02.01/doctest-2026.02.01.txz">
12+
<!ENTITY txzSHA256 "961ef8250303d3da11aa546308d82553518494b6819039ac4129e8c0ea24de8a">
13+
]>
14+
15+
<PLUGIN name="&name;"
16+
author="&author;"
17+
version="&version;"
18+
launch="&launch;"
19+
pluginURL="&pluginURL;"
20+
icon="flask"
21+
min="6.9.0"
22+
support="https://github.com/mstrhakr/unraid-plugin-docs"
23+
project="https://github.com/mstrhakr/unraid-plugin-docs"
24+
readme="https://github.com/mstrhakr/unraid-plugin-docs/blob/main/validation/README.md"
25+
>
26+
27+
<CHANGES>
28+
### 2026.02.01
29+
- Initial release
30+
- Validates: events, page files, config parsing, $var array, notifications
31+
</CHANGES>
32+
33+
<!-- Create plugin directory on flash -->
34+
<FILE Run="/bin/bash">
35+
<INLINE>
36+
mkdir -p &pluginLOC;
37+
</INLINE>
38+
</FILE>
39+
40+
<!-- Download and install the package -->
41+
<FILE Name="&pluginLOC;/&txzName;">
42+
<URL>&txzURL;</URL>
43+
<SHA256>&txzSHA256;</SHA256>
44+
</FILE>
45+
46+
<FILE Run="/bin/bash">
47+
<INLINE>
48+
# Install the package
49+
upgradepkg --install-new &pluginLOC;/&txzName;
50+
51+
# Initialize event log
52+
echo "=== DocTest Event Log ===" > /var/log/doctest-events.log
53+
echo "Plugin installed: $(date '+%Y-%m-%d %H:%M:%S')" >> /var/log/doctest-events.log
54+
echo "Unraid version: $(cat /etc/unraid-version | grep version | cut -d'"' -f2)" >> /var/log/doctest-events.log
55+
echo "---" >> /var/log/doctest-events.log
56+
57+
logger -t "doctest" "DocTest validation plugin installed"
58+
echo "DocTest validation plugin installed. Go to Settings → DocTest Validation"
59+
</INLINE>
60+
</FILE>
61+
62+
<!-- Removal script -->
63+
<FILE Run="/bin/bash" Method="remove">
64+
<INLINE>
65+
# Remove the package
66+
removepkg &name;
67+
68+
# Remove plugin files
69+
rm -rf &emhttpLOC;
70+
rm -rf &pluginLOC;
71+
rm -f /var/log/doctest-events.log
72+
rm -f /tmp/doctest_poll_logged
73+
74+
logger -t "doctest" "DocTest validation plugin removed"
75+
echo "DocTest validation plugin removed"
76+
</INLINE>
77+
</FILE>
78+
79+
</PLUGIN>

‎validation/plugin/build.sh‎

Lines changed: 71 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,71 @@
1+
#!/bin/bash
2+
#
3+
# build.sh - Build the doctest validation plugin
4+
# Part of: https://github.com/mstrhakr/unraid-plugin-docs
5+
#
6+
# Usage: ./build.sh [version]
7+
# version: Optional version string (default: 2026.02.01)
8+
#
9+
10+
set -e
11+
12+
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
13+
BUILD_DIR="$SCRIPT_DIR/build"
14+
DIST_DIR="$SCRIPT_DIR/dist"
15+
SOURCE_DIR="$SCRIPT_DIR/source"
16+
VERSION="${1:-2026.02.01}"
17+
PLUGIN_NAME="doctest"
18+
19+
echo "Building $PLUGIN_NAME version $VERSION"
20+
21+
# Clean previous builds
22+
rm -rf "$BUILD_DIR" "$DIST_DIR"
23+
mkdir -p "$BUILD_DIR" "$DIST_DIR"
24+
25+
# Create package directory structure
26+
mkdir -p "$BUILD_DIR/usr/local/emhttp/plugins/$PLUGIN_NAME"
27+
mkdir -p "$BUILD_DIR/usr/local/emhttp/plugins/$PLUGIN_NAME/event"
28+
29+
# Copy source files
30+
cp -R "$SOURCE_DIR/emhttp/"* "$BUILD_DIR/usr/local/emhttp/plugins/$PLUGIN_NAME/"
31+
32+
# Convert Windows line endings to Unix (in case developed on Windows)
33+
find "$BUILD_DIR" -type f \( -name "*.sh" -o -name "*.page" -o -name "*.cfg" \) -exec sed -i 's/\r$//' {} \;
34+
find "$BUILD_DIR/usr/local/emhttp/plugins/$PLUGIN_NAME/event" -type f -exec sed -i 's/\r$//' {} \;
35+
36+
# Set permissions
37+
find "$BUILD_DIR" -type d -exec chmod 755 {} \;
38+
find "$BUILD_DIR" -type f -exec chmod 644 {} \;
39+
find "$BUILD_DIR" -name "*.sh" -exec chmod 755 {} \;
40+
find "$BUILD_DIR/usr/local/emhttp/plugins/$PLUGIN_NAME/event" -type f -exec chmod 755 {} \;
41+
42+
# Create the TXZ package
43+
cd "$BUILD_DIR"
44+
TXZ_FILE="${PLUGIN_NAME}-${VERSION}.txz"
45+
tar -cJf "$DIST_DIR/$TXZ_FILE" .
46+
echo "Created: $DIST_DIR/$TXZ_FILE"
47+
48+
# Calculate SHA256
49+
cd "$DIST_DIR"
50+
TXZ_SHA256=$(sha256sum "$TXZ_FILE" | cut -d' ' -f1)
51+
echo "SHA256: $TXZ_SHA256"
52+
53+
# Generate PLG file from template
54+
sed -e "s|{{VERSION}}|${VERSION}|g" \
55+
-e "s|{{TXZ_SHA256}}|${TXZ_SHA256}|g" \
56+
-e "s|{{TXZ_NAME}}|${TXZ_FILE}|g" \
57+
"$SCRIPT_DIR/doctest.plg.template" > "$DIST_DIR/${PLUGIN_NAME}.plg"
58+
59+
echo "Created: $DIST_DIR/${PLUGIN_NAME}.plg"
60+
61+
# Copy to validation root for easy access
62+
cp "$DIST_DIR/${PLUGIN_NAME}.plg" "$SCRIPT_DIR/../doctest.plg"
63+
64+
echo ""
65+
echo "Build complete!"
66+
echo " Package: $DIST_DIR/$TXZ_FILE"
67+
echo " Plugin: $DIST_DIR/${PLUGIN_NAME}.plg"
68+
echo ""
69+
echo "To install on an Unraid server:"
70+
echo " 1. Copy $TXZ_FILE and ${PLUGIN_NAME}.plg to the server"
71+
echo " 2. Run: plugin install /path/to/${PLUGIN_NAME}.plg"

‎validation/plugin/doctest-local.plg‎

Lines changed: 80 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,80 @@
1+
<?xml version='1.0' standalone='yes'?>
2+
<!DOCTYPE PLUGIN [
3+
<!ENTITY name "doctest">
4+
<!ENTITY author "unraid-plugin-docs">
5+
<!ENTITY version "2026.02.01">
6+
<!ENTITY launch "Settings/DocTest">
7+
<!ENTITY pluginLOC "/boot/config/plugins/&name;">
8+
<!ENTITY emhttpLOC "/usr/local/emhttp/plugins/&name;">
9+
<!ENTITY txzName "doctest-2026.02.01.txz">
10+
]>
11+
12+
<PLUGIN name="&name;"
13+
author="&author;"
14+
version="&version;"
15+
launch="&launch;"
16+
icon="flask"
17+
min="6.9.0"
18+
support="https://github.com/mstrhakr/unraid-plugin-docs"
19+
project="https://github.com/mstrhakr/unraid-plugin-docs"
20+
readme="https://github.com/mstrhakr/unraid-plugin-docs/blob/main/validation/README.md"
21+
>
22+
23+
<CHANGES>
24+
### 2026.02.01
25+
- Initial release
26+
- Validates: events, page files, config parsing, $var array, notifications
27+
</CHANGES>
28+
29+
<!-- Create plugin directory on flash -->
30+
<FILE Run="/bin/bash">
31+
<INLINE>
32+
mkdir -p &pluginLOC;
33+
</INLINE>
34+
</FILE>
35+
36+
<!-- Copy pre-built package from /tmp (for local testing) -->
37+
<FILE Run="/bin/bash">
38+
<INLINE>
39+
# Check if package exists in /tmp
40+
if [ -f "/tmp/doctest-build/&txzName;" ]; then
41+
cp "/tmp/doctest-build/&txzName;" "&pluginLOC;/"
42+
echo "Copied package from /tmp/doctest-build/"
43+
else
44+
echo "ERROR: Package not found at /tmp/doctest-build/&txzName;"
45+
echo "Please build the package first or use the online version"
46+
exit 1
47+
fi
48+
49+
# Install the package
50+
upgradepkg --install-new &pluginLOC;/&txzName;
51+
52+
# Initialize event log
53+
echo "=== DocTest Event Log ===" > /var/log/doctest-events.log
54+
echo "Plugin installed: $(date '+%Y-%m-%d %H:%M:%S')" >> /var/log/doctest-events.log
55+
echo "Unraid version: $(cat /etc/unraid-version | grep version | cut -d'"' -f2)" >> /var/log/doctest-events.log
56+
echo "---" >> /var/log/doctest-events.log
57+
58+
logger -t "doctest" "DocTest validation plugin installed"
59+
echo "DocTest validation plugin installed. Go to Settings → DocTest Validation"
60+
</INLINE>
61+
</FILE>
62+
63+
<!-- Removal script -->
64+
<FILE Run="/bin/bash" Method="remove">
65+
<INLINE>
66+
# Remove the package
67+
removepkg &name;
68+
69+
# Remove plugin files
70+
rm -rf &emhttpLOC;
71+
rm -rf &pluginLOC;
72+
rm -f /var/log/doctest-events.log
73+
rm -f /tmp/doctest_poll_logged
74+
75+
logger -t "doctest" "DocTest validation plugin removed"
76+
echo "DocTest validation plugin removed"
77+
</INLINE>
78+
</FILE>
79+
80+
</PLUGIN>

0 commit comments

Comments
 (0)