
                 The Netatalk Test-Suite
                 =======================

This suite contains several small utilities aimed at testing
a) AFP Server conformance to the AFP Specs, e.g. `afp_spectest`
b) benchmarking AFP Servers, e.g. `afp_lantest` and `afp_speedtest`

For end users the most useful utility is probably `afp_lantest` which
is a CLI counterpart for the famous HELIOS Lan Test.

Tests prg in test directory:
============================

Spec conformance tests
----------------------

./afp_spectest:
AFP spec test. Assume exported volumes are only modified with netatalk.
Contains multiple test suites, activated with the -F option.

List of available spec test suites:

- tier1
Baseline AFP specification tests.
This is the default without the -F option.

- tier2
AFP spec tests when .AppleDouble is missing or bogus.
Requires local access to volume (-c option).

- readonly
AFP spec tests on a read only volume.
Requires read only volume with at least 2 files and 1 folder (empty).

- sleep
AFP spec tests for sleeping (FPZzz).

./afp_logintest:
AFP spec tests for DSI and login. Not included in spectest.

./afp_encodingtest:
AFP spec tests for encoding. Not included in spectest.


Benchmarking
------------

./afp_lantest
Netatalk implementation of HELIOS Lan Test.

./afp_speedtest
Bench Read, Write and file copy (either Read/Write or FPCopyFile),
it can also run the same tests using Posix syscalls and can
be use for testing afpd speed against local or others protocols.


Helpers
-------

./afparg
The beginning of an AFP CLI client, cf ./afparg -l
FPResolveID <file CNID>
FPCopyFile <source> <dest>

./afp_ls
'minimal' ls using AFP commands. Should be migrated to afparg.

Compilation
===========

Setup meson with the `-Dwith-testsuite=true' option.
Then compile the netatalk package as usual.
The afptest binaries can be found under build/test/testsuite/


Configuration for running the APF spec tests
============================================

- 2 users: <user1> <user2> with the same password
- 3 group: <gp1> <gp2> <common>
- with gp1:user1, gp2:user2, common:user1, user2
- clear text UAM
- an empty volume:
drwxrwsr-x    5 user1   common         176 avr 27 23:56 test/
- some tests need a small read write volume, I'm using a 2 MBytes loopback

example for
afp.conf:
#<<<<<<
[Global]
uam list = uams_clrtxt.so uams_guest.so

[test1]
path = /tmp/afptest1

[test2]
path = /tmp/afptest2
#<<<<<<<<

For testing with a Mac, same config (user1 or user2 are not owner)

meson test
----------

You can also run the complete spectest (one user, two users, local access) with
`meson test`. To do so, run:
- `cd build && meson test` once in order to generate a boilerplate config file "spectest.conf"
- edit "build/test/testsuite/spectest.conf" to suit your needs
- run `meson test` again

Return Codes
------------
0 PASSED
1 FAILED
2 NOT TESTED - a test setup step or precondition check failed
3 SKIPPED - test environment requirements not satisfied

Note that 2 and 3 are treated as an overall return code 0 for the purpose of test reporting.

spectest, logintext and rotest shall return the same results whether they are run
on a Mac server or afpd.

Example:
--------
Run all tier 1 spec tests on server 192.168.2.123
afp_spectest -F tier1 -h 192.168.2.123 -u user1 -d usr2 -s test -w toto
Same but on a Mac
afp_spectest -F tier1 -m -h 192.168.2.64 -u user1 -d usr2 -s test -w toto

Run FPByteRangeLock tests with AFP 3.0, two different servers are exporting the same volume.
afp_spectest -f FPByteRangeLock -3 -h 192.168.2.123 -H 192.168.2.124 -u user1 -d usr2 -s test -c /tmp/afptest1 -w toto

At least on linux, it's possible to compile them with LDFLAGS=-rdynamic
and the program can run individual test:
afp_spectest -4 -u <user> -d <seconduser> -w <passwd> -s <vol> -c <path> -f test235

Tests output
------------

Test name
if the test is not executed, reason, ex: SKIPPED (need AFP 3.x)
list of AFP calls executed with error code if any

- if Mac result and Netatalk differ or if Mac result differ between versions, Mac result
Ex:
header.dsi_code       -5000     AFPERR_ACCESS
MAC RESULT: -5019 AFPERR_PARAM    -5010 AFPERR_BUSY
Netatalk returns AFPERR_ACCESS when a Mac return AFPERR_PARAM or AFPERR_BUSY

- if Mac and Netatalk now return the same result:
Warning MAC and Netatalk now same RESULT!

List tests
----------

One way to get a list of tests that are actually implemented,
is to grep for symbols in the compiled binaries.

nm afp_encoding_test afp_spectest_fail afp_speedtest afp_spectest afp_spectest_t2 afp_logintest afp_rotest | cut -d " " -f 3 | egrep "^test[[:digit:]]+" | sort -n -k 1.5
