From 5593341b047370a24f82fa79a948d9b0836c2fca Mon Sep 17 00:00:00 2001
From: Timothy Allen <tim@treehouse.org.za>
Date: Sat, 26 Sep 2026 03:48:09 +0200
Subject: [PATCH] Add a README for the tests, and block the development files.

---
 .htaccess | 10 ++++++++
 README.md | 72 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 82 insertions(+)
 create mode 100644 README.md

diff --git a/.htaccess b/.htaccess
index c8ed73f..6bae000 100644
--- a/.htaccess
+++ b/.htaccess
@@ -5,3 +5,13 @@
 <FilesMatch "^\.">
   Require all denied
 </FilesMatch>
+
+# Do not serve the development files: the tests, the packages that
+# Composer and npm install, and their configuration. These files are not
+# needed on the live site (see README.md).
+<If "%{REQUEST_URI} =~ m#^/(vendor|node_modules|tests)(/|$)#">
+  Require all denied
+</If>
+<FilesMatch "^(composer\.(json|lock|phar)|package(-lock)?\.json|phpunit\.xml(\.dist)?)$">
+  Require all denied
+</FilesMatch>
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..58058de
--- /dev/null
+++ b/README.md
@@ -0,0 +1,72 @@
+# xxx.org.za
+
+A Content Management System for x.x.x, a collection of 100-word stories.
+
+This code was mostly written between 2004 and 2008, although the git history
+doesn't stretch that far. If you're wondering why some core ports don't use
+fancy new PHP features... that's probably why.
+
+The site reads its configuration from `.env`. Copy `.env.example` to
+`.env`, and set the values in it.
+
+## Tests
+
+The repository has three sets of tests:
+
+- The PHP unit tests (`tests/php/Unit`) run the functions of the site
+  against a fake database. They do not need MySQL or the network.
+- The PHP page tests (`tests/php/Pages`) run the pages on the PHP
+  built-in web server, and send HTTP requests to them.
+- The JavaScript tests (`tests/js`) run the story editor and the other
+  scripts in jsdom, a browser document for Node.js.
+
+No test uses the real database, the real `.env` file, Google, or a mail
+server. The tests use `tests/php/fixtures/test.env` for the
+configuration, and they write only to the system temporary directory.
+
+### Requirements
+
+- PHP 8.4.1 or later on the command line, with the dom, filter, json,
+  libxml, mbstring, simplexml and xmlwriter extensions. The mysqli
+  extension is not necessary.
+- Composer.
+- Node.js 20.19, 22.13, or 24 or later, with npm.
+
+### Run the PHP tests
+
+Install PHPUnit and the other development packages into `vendor/`:
+
+```sh
+composer install
+```
+
+Run all the PHP tests:
+
+```sh
+composer test
+```
+
+### Run the JavaScript tests
+
+Install jsdom into `node_modules/`, then run the tests:
+
+```sh
+npm install
+npm test
+```
+
+To run one file:
+
+```sh
+node --test tests/js/editor.test.js
+```
+
+### Development files on the live site
+
+Do not install the development packages on the live server. The site itself
+does not use them.
+
+If the tests or the packages are on the server, `.htaccess` stops Apache from
+serving `tests/`, `vendor/`, `node_modules/` and the Composer, npm and PHPUnit
+files. This needs `AllowOverride AuthConfig`, as the other rules in `.htaccess`
+do.