From d6368447d86a4cac14dc45ed0e8a101b133afd8d Mon Sep 17 00:00:00 2001 From: Thomas Sawyer Date: Sun, 27 Sep 2026 15:25:03 -0400 Subject: [PATCH 1/2] docs: explain the Facets test stack :doc: --- CONTRIBUTING.md | 52 +++++++++++++++++++++++++++++++++++++------------ 1 file changed, 40 insertions(+), 12 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 77a1faa41..3a071a2b7 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -18,10 +18,9 @@ The Lemon unit tests are for testing a method in detail whereas the QED demos are for demonstrating usage. -* Facets is divided into two parts, *core* and *standard* libraries. - Almost all of the core library can be loaded at once using `require 'facets'` - The standard library (also called the *more* library) must be required - per-script. +* Facets has *core*, *standard*, and Rails-compatible library areas. + Almost all core extensions can be loaded at once with `require 'facets'`. + Standard and Rails-compatible extensions should be required by file. * Some core methods are included on a *trial* basis, and these are not necessary loaded automatically with `require 'facets'`. These should be @@ -102,11 +101,40 @@ explanation if needed, including *when* and *why* the method could be useful. ## Testing -* Methods in `lib/core/facets/{class}/{method}.rb` will be tested in `test/foo/{class}/test_{method}.rb`. -* If `lib/core/facets/{class}/{method}.rb` consists only of a require statement, no test file is expected. -* If `lib/core/facets/{class}/{method}.rb` consists only of a require and an alias, then `test/foo/{class}/{method}.rb`, only needs to test the existence of the alias and not the underlying code. But it's okay if the alias is tested further. -* Methods in `lib/core/facets/{class}/{method}.rb` will be demoed in `demo/core/{class}/{method}.md`. -* Require only files will have a full demo of it's method or methods. Code in a single file may be split into multiple demos, named after the method. This is to promote discoverability in the documentation. -* Demos of aliases will have a simple demo, and a reference to the file it aliases - - +The test suite uses four tools: + +* **RubyTest** provides the test runner interface; `rubytest-cli` supplies the + `ruby-test` command used by the Rake tasks. +* **Lemon** defines the `test_case`, `method`, and `test` structure of the unit + tests. +* **AE** provides assertions such as `.assert` and `expect` inside those tests. + It is installed as a Lemon dependency. +* **QED** runs the executable examples in `demo/`. They show how a method is + intended to be used as well as checking its behavior. + +Install the development dependencies and run the same two suites as CI: + +```sh +bundle install +bundle exec rake test +bundle exec rake qed +``` + +For a focused unit test, set `TESTS` to a test file, for example: + +```sh +TESTS=test/core/array/test_average.rb bundle exec rake test +``` + +The Rakefile also provides `test:core`, `test:standard`, `test:rails` and the +corresponding `qed:*` tasks for each library area. + +* A core method in `lib/core/facets/{class}/{method}.rb` normally has a Lemon + test in `test/core/{class}/test_{method}.rb` and a QED demo in + `demo/core/{class}/{method}.md`. Standard and Rails-compatible libraries use + their respective `test/` and `demo/` directories. +* A file that only requires another file does not need its own unit test. A file + that also defines an alias can test the alias without repeating every test + for the underlying method. +* Demos should show the behavior of each method. An alias can have a short demo + that points readers to the main method's demo. From 289b0d1cd61b18453f1321dc40557b6beabe471e Mon Sep 17 00:00:00 2001 From: Thomas Sawyer Date: Sun, 27 Sep 2026 15:28:31 -0400 Subject: [PATCH 2/2] docs: clarify library area names :doc: --- CONTRIBUTING.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3a071a2b7..2af9b7954 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -18,9 +18,9 @@ The Lemon unit tests are for testing a method in detail whereas the QED demos are for demonstrating usage. -* Facets has *core*, *standard*, and Rails-compatible library areas. +* Facets groups libraries into `core`, `standard`, and `rails` areas. Almost all core extensions can be loaded at once with `require 'facets'`. - Standard and Rails-compatible extensions should be required by file. + Standard and rails extensions should be required by file. * Some core methods are included on a *trial* basis, and these are not necessary loaded automatically with `require 'facets'`. These should be @@ -131,7 +131,7 @@ corresponding `qed:*` tasks for each library area. * A core method in `lib/core/facets/{class}/{method}.rb` normally has a Lemon test in `test/core/{class}/test_{method}.rb` and a QED demo in - `demo/core/{class}/{method}.md`. Standard and Rails-compatible libraries use + `demo/core/{class}/{method}.md`. Standard and rails libraries use their respective `test/` and `demo/` directories. * A file that only requires another file does not need its own unit test. A file that also defines an alias can test the alias without repeating every test