AFP_SPECTEST(1)

🎀 NAME 🎀

Hey bestie! 💖 This is the AFP_SPECTEST(1) page from the Netatalk AFP Fileserver Manual, and it's all about afp_spectest, the AFP specification compliance test suite ✨

💅 SYNOPSIS 💅

Okay, here's how you call it:

afp_spectest [-1234567aCEimVv] [-h host] [-H host2] [-p port] [-s
volume] [-c path to volume] [-S volume2] [-u user] [-d user2] [-w
password] [-f test]

afp_spectest -l

🌸 DESCRIPTION 🌸

afp_spectest is a comprehensive AFP specification test suite with several hundreds of test cases 🤯 The tests are sorted into testsets, grouped either by the AFP command being tested or by the preconditions needed to test it 🧚

You can see every available testset with -l. Want to run a single test or a whole testset? Use -f 🦋

✨ OPTIONS ✨

Okay, the options are where it gets spicy 🌶️ Here's the whole menu:

• -1 — Uses the AFP 2.1 protocol version 💫
• -2 — Uses the AFP 2.2 protocol version 💫
• -3 — Uses the AFP 3.0 protocol version 💫
• -4 — Uses the AFP 3.1 protocol version 💫
• -5 — Uses the AFP 3.2 protocol version 💫
• -6 — Uses the AFP 3.3 protocol version 💫
• -7 — Uses the AFP 3.4 protocol version. This one's the default 👑
• -a — Tells the test runner that the server under test stores AppleDouble v2 metadata, not filesystem EA 🗂️
• -c path — The local filesystem path to the test volume. You need this for tier 2 tests 🛠️
• -C — Turns off ANSI colors in the terminal output. No rainbows for you 🌈
• -d user — A second username for logging in to the AFP server 👯
• -E — Empties the test volume before the tests run 🧹

WARNING: This will delete all files and directories in the test volume! Do NOT point this at a volume you actually care about 💀

• -f test — Picks the test or testset you want to run 🎯
• -h host — The server hostname or IP address. It defaults to localhost 🏠
• -H host — The server hostname or IP address for the second host 🖥️
• -i — Interactive mode! It asks you before each test. Mostly for debugging 🔍
• -l — Lists every available testset, then exits 📜
• -m — Runs the tests in AppleShare (Mac) AFP server compatibility mode 🍎
• -p port — The server port number. The default is 548 🔌
• -s volume — The volume name to mount for testing 📂
• -S volume — The volume name for a second volume to mount for testing 📁
• -u user — The username for logging in to the AFP server. It defaults to the current uid 🙋
• -v — Verbose output 📣
• -V — Very verbose output. Extra chatty, extra iconic 📢
• -w password — The password for logging in to the AFP server 🔐

🧠 USAGE 🧠

Every test in the spectest suite follows the same general pattern and parameters. Some tests need extra required parameters or preconditions, though 🤓 First you set the AFP protocol version (-1 through -7), then you give the address and credentials of the host you're testing. That host can be localhost. Some tests also need a second user and a second volume defined 👯‍♀️

The so-called tier 2 (T2) tests have to run from localhost, and you have to give the local path to the volume under test with -c. Why? They modify the file system directly with system calls, both to set up preconditions and to check results 🛠️

There are also read-only and sleep tests, and those have to be run separately 🫶

🔮 Extension mapping tests

A handful of tests in the FPGetFileDirParms testset expect the filename extension to Classic Mac OS Type/Creator mapping to be turned on. In version 3 and later of netatalk, you have to enable this yourself by editing extmap.conf(5). Uncomment the lines for the mappings you want in that configuration file 🎀

😴 Sleep tests

The FPzzz testset holds tests for AFP sleep mode and timeouts. These take way longer than everything else, so they're not included when you run the full spectest suite 🐢 You have to run that testset on its own with -f:

afp_spectest -f FPzzz

👀 Readonly tests

As the name suggests, the Readonly testset checks how netatalk behaves when the shared volume is in read-only mode 📖

Obviously, the volume you test has to be configured as read-only. You can do that by setting read only = yes in afp.conf, for example:

[test volume]
path = /my/path
volume name = test_volume
read only = yes

The tests expect at least two files and one directory in the read-only shared volume. Set that up like this:

echo "testfile uno" > /my/path/first.txt
echo "testfile dos" > /my/path/second.txt
mkdir /my/path/third

Then run the Readonly testset:

afp_spectest -s test_volume -f Readonly

🚦 Return codes

Each test in a testsuite returns one of these return codes:

• 0 — PASSED 🎉
• 1 — FAILED 😭
• 2 — NOT TESTED 🫠
• 3 — SKIPPED 🙈

NOT TESTED means a test setup step or precondition check failed. This return code flags the whole test run as failed, so it's a big deal 💀

SKIPPED means the test doesn't apply to the AFP server you're testing, or a parameter the test needs is missing. Check the test report for the specific reason it got skipped. This one won't count against your test run ✨

🍎 Testing an AppleShare AFP server

This suite was designed mainly for Netatalk AFP servers, but it can also test an AppleShare AFP server hosted by an older Mac OS X or Classic Mac OS system 💜

To test an AppleShare server, launch the test runner with the -m (Mac) option. In this mode, the runner reports tests with known current or historical differences between AppleShare and Netatalk 🍓

If AppleShare and Netatalk differ, or if AppleShare results differ between versions, you'll see something like this:

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

When AppleShare and Netatalk used to return different results but now behave the same way, you'll get this:

Warning MAC and Netatalk now same RESULT!

Apart from these cases, the spectest should return the same results whether you run it against a native AppleShare AFP server or against Netatalk 🫶

📚 EXAMPLES 📚

⚙️ Configure environment

Here's a sample setup for running the AFP spec tests. Right now, the test runner only supports ClearTxt and Guest authentication 🔑

• 2 users: user1 and user2, with the same password
• 1 group: afpusers
• user1 and user2 are both in the afpusers group

Arrange two empty directories. Some tests will fail if there are leftover files in the test directories 🧹

drwxrwsr-x    5 user1   afpusers       176 avr 27 23:56 /tmp/afptest1
drwxrwsr-x    5 user1   afpusers       176 avr 27 23:56 /tmp/afptest2

Then set up afp.conf like this:

[Global]
uam list = uams_clrtxt.so uams_guest.so

[testvol1]
ea = sys
path = /tmp/afptest1
valid users = @afpusers
volume name = testvol1

[testvol2]
ea = sys
path = /tmp/afptest2
valid users = @afpusers
volume name = testvol2

🏃‍♀️ Running tests

Let's run afp_spectest against the AFP server on 10.0.0.10, using the FPSetForkParms_test testset with AFP 3.4 💅

% afp_spectest -h 10.0.0.10 -u user1 -d user2 -w passwd -s testvol1 -S testvol2 -c /srv/afptest1 -7 -f FPSetForkParms_test
===================
FPSetForkParms_test
-------------------
FPSetForkParms:test62: SetForkParams errors - PASSED
FPSetForkParms:test141: Setforkmode error - PASSED
FPSetForkParms:test217: Setfork size 64 bits - PASSED
FPSetForkParms:test306: set fork size, new size > old size - PASSED

🔗 SEE ALSO 🔗

Check out these friends too 🧚

• afp_logintest(1)
• afparg(1)
• afpd(8)

---

That's the whole tea, bestie! 🫶 This page came from Netatalk 4.5.1, and it's AFP_SPECTEST(1) all the way through. Stay iconic and keep testing 💖✨