Add a README for the tests, and block the development files.

2026-09-26 15:27:51 +02:00
parent b7022ab486
commit 5593341b04
2 changed files with 82 additions and 0 deletions
@@ -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>
@@ -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.