Doc needs help

What are the options? It turns out they don't do anything, at least for now (see below).

The source code (click on the ':-' symbol at the top right of the page) reveals that for every Prolog source file loaded, it looks for a file named the same, in the same location, with a `.plt` suffix, and if so it calls:

   load_files(TestFile,
              [ if(changed),        % "loads the file if not loaded modified since last load"
                imports([])         % It think this means "import nothing"?
              ]),

The passed Options is not used for anything!

See load_files/2

Note about the manual

There are two entries for load_test_files

• Under "packages" (this page): https://eu.swi-prolog.org/pldoc/doc_for?object=load_test_files/1
  • It's the one you find when performing "search documentation"
• Under "libraries": https://eu.swi-prolog.org/pldoc/doc_for?object=plunit%3Aload_test_files/1
  • It's the one linked to when you add a dynamic link here, like so: load_test_files/1

Relatively confusing.

Deterministic

• load_test_files/1 always succeeds, even if there are no files to load.
• it does not reload already-loaded files! use make/0 for that

.plt file must be right next to the .pl file

load_test_files/1 looks for files that have the same name as a loaded file, but with the suffix changed from `.pl to .plt`. It does not content analysis (i.e. look for plunit module declarations) in the file content. Nor does it look in subdirectories i.e. you cannot put the .plt files into a `test/` subdirectory.

Modified to provide some output

Here is a modified load_test_files/2 which builds a list of skipped or loaded test files.

That's much more informative than the "silent" load_test_files/1.

Otherwise it has the exact same functionality.

load_test_files(_Options,Which) :-
   (nonvar(Which) ->                             % "Which" will be set
   '$uninstantiation_error'(Which)               % and thus must be uninstantiated
   ; true),
   findall(Pair,test_file(Pair),Pairs),          % collect File-TestFile pairs (load order probably unimportant)
   load_test_files_2(Pairs,Which).               % load and side-effect the Prolog database
   
test_file(File-TestFile) :-
   source_file(File),                            % File is a previously loaded source file
   file_name_extension(Base, Old, File),         % and which can be decomposed into Base (maybe with path) and suffix Old
   Old \== plt,                                  % and which does not have a .plt extension
   file_name_extension(Base, plt, TestFile),     % and which can be recomposed into TestFile
   exists_file(TestFile).                        % and for which TestFile exists on-disk

% ---
% Loading loop
% ---

load_test_files_2([],[]).

load_test_files_2([File-TestFile|Pairs],[skipped(TestFile)|Which]) :-
   plunit:test_file_for(TestFile, File),         % do nothing if already loaded
   !,
   load_test_files_2(Pairs,Which).
   
load_test_files_2([File-TestFile|Pairs],[loaded(TestFile)|Which]) :-
   load_files(TestFile,
              [ if(changed),                     % "loads the file if not loaded modified since last load"
                imports([])                      % "import nothing"?
              ]),
   asserta(plunit:test_file_for(TestFile, File)),
   load_test_files_2(Pairs,Which).

So for example:

?- load_test_files([],Which).
Which = [loaded('/home/user/Development/PACKING/prolog_code/tmp/texty_typetests.plt')].

?- load_test_files([],Which).
Which = [skipped('/home/user/Development/PACKING/prolog_code/tmp/texty_typetests.plt')].

Some module magic problem

For some reason this does not work for "raw code" files, i.e. files whose code gets loaded into module "user", as opposed to files that properly declare modules.

Although a `.plt` file is loaded, the tests fail because they look for the "predicate-under-test" in the wrong module.

Example:

In file foo.pl

a(X) :- 0 =:= X mod 3.

In file foo.plt

:- begin_tests(footest).

test("3 is ok")          :- a(3).
test("2 is not ok",fail) :- a(2).

:- end_tests(footest).

Then:

?- [foo].
true.

?- load_test_files([]).
true.

?- run_tests.
% PL-Unit: footest
ERROR: foo.plt:3:
        test 3 is ok: received error: setup_call_catcher_cleanup/4: Unknown procedure: plunit_footest:a/1
ERROR: foo.plt:4:
        test 2 is not ok: received error: catch/3: Unknown procedure: plunit_footest:a/1
 done
% 2 tests failed
% 0 tests passed
false.

BUT

In file foo.pl

:- module(foo,[a/1]).

a(X) :- 0 =:= X mod 3.

In file foo.plt:

:- use_module(['foo.pl']).

:- begin_tests(footest).

test("3 is ok")          :- a(3).
test("2 is not ok",fail) :- a(2).

:- end_tests(footest).

then

?- [foo].
true.

?- load_test_files([]).
true.

?- run_tests.
% PL-Unit: footest .. done
% All 2 tests passed
true.