Add some documentation to make the unit tests easier to follow

[raboof]

See also https://issues.apache.org/jira/browse/VFS-855

[garydgregory]

@raboof
Thank you for the PR.

IMO: I think we should note that this testing framework originated when we used JUnit 3 and that we want to update it to JUnit 5 which would make some of this complex and awkward test set up no longer necessary.

[raboof]

Makes sense, filed https://issues.apache.org/jira/browse/VFS-855 and linked to that

[garydgregory]

I canceled and restarted the failing builds.

Maybe one of the SSH tests is hung:

[INFO] Running org.apache.commons.vfs2.provider.sftp.SftpPutChannelTestCase
Exception in thread "pool-34-thread-1" java.lang.AssertionError
	at org.apache.sshd.common.session.AbstractSession.decode(AbstractSession.java:519)
	at org.apache.sshd.common.session.AbstractSession.messageReceived(AbstractSession.java:236)
	at org.apache.sshd.common.AbstractSessionIoHandler.messageReceived(AbstractSessionIoHandler.java:58)
	at org.apache.mina.core.filterchain.DefaultIoFilterChain$TailFilter.messageReceived(DefaultIoFilterChain.java:1015)
	at org.apache.mina.core.filterchain.DefaultIoFilterChain.callNextMessageReceived(DefaultIoFilterChain.java:650)
	at org.apache.mina.core.filterchain.DefaultIoFilterChain.access$1300(DefaultIoFilterChain.java:49)
	at org.apache.mina.core.filterchain.DefaultIoFilterChain$EntryImpl$1.messageReceived(DefaultIoFilterChain.java:1128)
	at org.apache.mina.core.filterchain.IoFilterAdapter.messageReceived(IoFilterAdapter.java:122)
	at org.apache.mina.core.filterchain.DefaultIoFilterChain.callNextMessageReceived(DefaultIoFilterChain.java:650)
	at org.apache.mina.core.filterchain.DefaultIoFilterChain.fireMessageReceived(DefaultIoFilterChain.java:643)
	at org.apache.mina.core.polling.AbstractPollingIoProcessor.read(AbstractPollingIoProcessor.java:539)
	at org.apache.mina.core.polling.AbstractPollingIoProcessor.access$1200(AbstractPollingIoProcessor.java:68)
	at org.apache.mina.core.polling.AbstractPollingIoProcessor$Processor.process(AbstractPollingIoProcessor.java:1224)
	at org.apache.mina.core.polling.AbstractPollingIoProcessor$Processor.process(AbstractPollingIoProcessor.java:1213)
	at org.apache.mina.core.polling.AbstractPollingIoProcessor$Processor.run(AbstractPollingIoProcessor.java:683)
	at org.apache.mina.util.NamePreservingRunnable.run(NamePreservingRunnable.java:64)
	at java.util.concurrent.ThreadPoolExecutor.runWorker(ThreadPoolExecutor.java:1149)
	at java.util.concurrent.ThreadPoolExecutor$Worker.run(ThreadPoolExecutor.java:624)
	at java.lang.Thread.run(Thread.java:750)

We are on an antique version of Mina, which I've tried to update in the past, but didn't manage to get working...

[raboof]

suspicious that it's macos-13, 8 each time it seems.

https://github.com/apache/mina-sshd/blob/sshd-0.8.0/sshd-core/src/main/java/org/apache/sshd/common/session/AbstractSession.java#L519

[garydgregory]

Yeah, pretty suspicious 🤔

[garydgregory]

Since this is only documentation, I'm going to merge it, and see if the random-ish failure goes away with the develop-Java-macos-13 combination.