Zephyr Library Tests

This file is a collection of doctests for the zephyr library.
Minimum coverage goal is "every non-static function, and every data
structure that shows up in those function prototypes."

This file is also a test of the practicality of rich doctests as API
documentation.  It will start out as a bunch of snippets, and later be
edited to use actual chapters and appendices - narrative structure
beyond "here's a test! here's another test!"  At that point we'll also
pick a formatting language (probably ReStructured Text but for now, we
need no more than whitespace separated paragraphs to be
comprehensible.)

Generic library setup that should be moved into zephyr_tests.py:

   >>> import os
   >>> import zephyr_tests
   >>> buildpath = zephyr_tests.find_buildpath()
   >>> libzephyr_path = os.path.join(buildpath, ".libs", "libzephyr.so.4.0.0")
   >>> _z = zephyr_tests.libZephyr(libzephyr_path)

ZInit() got run by libZephyr, internally.  Make sure other things
actually got set up:

   >>> assert _z.ZGetFD() == -1
   >>> Zauthtype = _z.Zauthtype
   >>> assert Zauthtype in (0, 4, 5)
   >>> realm = _z.ZGetRealm()
   >>> assert realm
   >>> if Zauthtype: assert realm != 'local-realm'
   >>> if not Zauthtype: assert realm == 'local-realm'
   >>> assert _z.ZGetSender()
   >>> assert "@" in _z.ZGetSender()

ZNotice_t structure pseudo-round-trip (needs a lot more explicit
settings and assertions to be a real round-trip test...)

   >>> notice = zephyr_tests.ZNotice_t()
   >>> from ctypes import sizeof
   >>> assert sizeof(notice) > 150
   >>> from ctypes import c_char_p, c_int
   >>> zbuf = c_char_p(0)
   >>> zbuflen = c_int(0)
   >>> st = _z.ZFormatNotice(notice, zbuf, zbuflen, zephyr_tests.ZNOAUTH)
   >>> assert st == 0
   >>> assert zbuf.value.startswith("ZEPH")
   >>> new_notice = zephyr_tests.ZNotice_t()
   >>> st = _z.ZParseNotice(zbuf, zbuflen, new_notice)
   >>> assert st == 0
   >>> assert new_notice.z_version.startswith("ZEPH")

Should we check for ZEPH0.2 now, or leave that open?

Simple test of ZCompareUID:

   >>> uid1 = zephyr_tests.ZUnique_Id_t()
   >>> uid2 = zephyr_tests.ZUnique_Id_t()
   >>> assert _z.ZCompareUID(uid1, uid2), "null uids don't match"

There's no ZUnique_Id_t constructor - Z_FormatHeader and
Z_NewFormatHeader initialize notice->z_uid directly, so cheat and use
ZNotice_t as the constructor...

   >>> notice1 = zephyr_tests.ZNotice_t()
   >>> zbuf = c_char_p(0)
   >>> zbuflen = c_int(0)
   >>> st = _z.ZFormatNotice(notice1, zbuf, zbuflen, zephyr_tests.ZNOAUTH)
   >>> assert st == 0, "ZFormatNotice notice1 failed"

   >>> notice2 = zephyr_tests.ZNotice_t()
   >>> zbuf = c_char_p(0)
   >>> zbuflen = c_int(0)
   >>> st = _z.ZFormatNotice(notice2, zbuf, zbuflen, zephyr_tests.ZNOAUTH)
   >>> assert st == 0, "ZFormatNotice notice1 failed"

   >>> assert not _z.ZCompareUID(notice1.z_uid, notice2.z_uid), "distinct notices don't compare as distinct"

Trivial test of ZExpandRealm, using terribly well known hostnames:

   >>> assert _z.ZExpandRealm("") == ""
   >>> if Zauthtype: assert _z.ZExpandRealm("localhost") == ""
   >>> if Zauthtype: assert _z.ZExpandRealm("bitsy.mit.edu") == "ATHENA.MIT.EDU"
   >>> if not Zauthtype: assert _z.ZExpandRealm("localhost") == "LOCALHOST"
   >>> if not Zauthtype: assert _z.ZExpandRealm("bitsy.mit.edu") == "BITSY.MIT.EDU"

Trivial test of ZOpenPort and ZClosePort:

   >>> from ctypes import c_ushort
   >>> port = c_ushort(0)
   >>> st = _z.ZOpenPort(port)
   >>> assert st == 0
   >>> assert _z.ZGetFD() != -1
   >>> assert port != 0

TODO: consider checking that ZGetFD is returning a socket on that port.

   >>> assert _z.ZClosePort() == 0
   >>> assert _z.ZGetFD() == -1

TODO: check that ZGetDestAddr points somewhere, too.

ZMakeAscii takes a target buffer and length and an input buffer and
length, and generates the "special" Zephyr encoding.

TODO: use the "reference" implementation to run a bunch of
random-value comparison tests.

   >>> sample = "test\0message"
   >>> ref = zephyr_tests.py_make_ascii(sample)
   >>> from ctypes import create_string_buffer
   >>> outlen = len(sample) * 6
   >>> outbuf = create_string_buffer(outlen)
   >>> st = _z.ZMakeAscii(outbuf, outlen, sample, len(sample))
   >>> assert st == 0
   >>> assert outbuf.value == ref, "%r != %r" % (outbuf.value, ref)

A few simple string tests:
   >>> def zma(sample):
   ...   outlen = len(sample) * 6
   ...   outbuf = create_string_buffer(outlen)
   ...   st = _z.ZMakeAscii(outbuf, outlen, sample, len(sample))
   ...   assert st == 0
   ...   return outbuf.value
   >>> zma("")
   ''
   >>> zma("j")
   '0x6A'
   >>> zma("jK")
   '0x6A4B'
   >>> zma("jK__\0")
   '0x6A4B5F5F 0x00'

Coverage:

Files complete:
   ZOpenPort.c
   ZClosePort.c
   ZExpnRlm.c
   ZCmpUID.c
   ZGetSender.c (needs richer test)

Pending:

ZRequestLocations (ZAsyncLocate.c)
ZParseLocations (ZAsyncLocate.c)
ZCompareALDPred (ZAsyncLocate.c)
ZFreeALD (ZAsyncLocate.c)
ZCheckAuthentication (ZCkAuth.c)
ZCheckIfNotice (ZCkIfNot.c)
ZCheckZcodeAuthentication (ZCkZAut.c)
ZCompareUIDPred (ZCmpUIDP.c)
ZCompareMultiUIDPred (ZCmpUIDP.c)
ZFlushLocations (ZFlsLocs.c)
ZFlushSubscriptions (ZFlsSubs.c)
ZFormatAuthenticNotice (ZFmtAuth.c)
ZFormatAuthenticNoticeV5 (ZFmtAuth.c)
ZFormatNoticeList (ZFmtList.c)
ZFormatNotice (ZFmtNotice.c)
ZNewFormatNotice (ZFmtNotice.c)
ZFormatRawNotice (ZFmtRaw.c)
ZFormatRawNoticeList (ZFmtRawLst.c)
ZFormatSmallRawNoticeList (ZFmtSmRLst.c)
ZFormatSmallRawNotice (ZFmtSmRaw.c)
ZNewFormatSmallRawNotice (ZFmtSmRaw.c)
ZFreeNotice (ZFreeNot.c)
ZGetLocations (ZGetLocs.c)
ZGetSubscriptions (ZGetSubs.c)
ZGetWGPort (ZGetWGPort.c)
ZIfNotice (ZIfNotice.c)
ZGetRealm (ZInit.c)
ZQLength (ZInit.c)
ZGetDestAddr (ZInit.c)
# not compiled anymore: ZLocateUser (ZLocateU.c)
ZInitLocationInfo (ZLocations.c)
ZSetLocation (ZLocations.c)
ZUnsetLocation (ZLocations.c)
ZFlushMyLocations (ZLocations.c)
ZParseExposureLevel (ZLocations.c)
Z_SendLocation (ZLocations.c)
ZMakeAscii32 (ZMakeAscii.c)
ZMakeAscii16 (ZMakeAscii.c)
ZMakeZcode32 (ZMakeZcode.c)
ZMakeZcode (ZMakeZcode.c)
ZResetAuthentication (ZMkAuth.c)
ZMakeAuthentication (ZMkAuth.c)
ZMakeZcodeAuthentication (ZMkAuth.c)
ZMakeZcodeRealmAuthentication (ZMkAuth.c)
ZGetCreds (ZMkAuth.c)
ZGetCredsRealm (ZMkAuth.c)
ZLocateUser (ZNewLocU.c)
ZParseNotice (ZParseNot.c)
ZPeekIfNotice (ZPeekIfNot.c)
ZPeekNotice (ZPeekNot.c)
ZPeekPacket (ZPeekPkt.c)
ZPending (ZPending.c)
ZReadAscii (ZReadAscii.c)
ZReadAscii32 (ZReadAscii.c)
ZReadAscii16 (ZReadAscii.c)
ZReadZcode (ZReadZcode.c)
ZReceiveNotice (ZRecvNot.c)
ZReceivePacket (ZRecvPkt.c)
ZRetrieveSubscriptions (ZRetSubs.c)
ZRetrieveDefaultSubscriptions (ZRetSubs.c)
ZSendList (ZSendList.c)
ZSrvSendList (ZSendList.c)
ZSendNotice (ZSendNot.c)
ZSrvSendNotice (ZSendNot.c)
ZSendPacket (ZSendPkt.c)
ZSendRawList (ZSendRLst.c)
ZSrvSendRawList (ZSendRLst.c)
ZSendRawNotice (ZSendRaw.c)
ZSetDestAddr (ZSetDest.c)
ZSetFD (ZSetFD.c)
ZSetServerState (ZSetSrv.c)
ZPunt (ZSubs.c)
ZSubscribeTo (ZSubs.c)
ZSubscribeToSansDefaults (ZSubs.c)
ZUnsubscribeTo (ZSubs.c)
ZCancelSubscriptions (ZSubs.c)
ZGetVariable (ZVariables.c)
ZSetVariable (ZVariables.c)
ZUnsetVariable (ZVariables.c)
Z_WaitForNotice (ZWait4Not.c)
ZhmStat (ZhmStat.c)

(...continue with Zinternal.c...)