Testing the Midi Kit====================Most of the Haiku source code has unit tests in the current/src/testsdirectory. I looked into building CppUnit tests for the midi2 kit, butdecided that it doesn't really make much sense. Unit tests work best ifyou can test something in isolation, but in the case of the midi2 kitthis is very hard to achieve. Because the classes from libmidi2.soalways need to talk to the midi_server, the tests depend on too manyexternal factors. The available endpoints, for example, will differ fromsystem to system. The spray and hook functions are difficult to testthis way, too.So instead of a CppUnit test suite, here is a list of manual tests thatI performed when developing the midi2 kit:--------------Registering the application---------------------------*Required:* Client app that calls BMidiRoster::MidiRoster()- When a client app starts, it should first receive mNEW notificationsfor all endpoints in the system (even unregistered remotes), followedby mCON notifications for all connections in the system (even thosebetween two unregistered local endpoints from another app).- Send invalid Mapp message (without messenger). The midi_serverignores the request, and the client app blocks forever.- Fake a delivery error for the mNEW notifications and the mAPP reply.(Add a snooze() in the midi_server's OnRegisterApplication(). Whileit is snoozing, Ctrl-C the client app. Now the server can't deliverthe message and will unregister the application again.)- Kill the server. Start the client app. It should realize that theserver is not running, and return from MidiRoster(); it does notblock forever.- Note: The server does not protect against sending two or more Mappmessages; it will add a new app_t object to the roster and it willalso send out the mNEW and mCON notifications again.- Verify that when the client app quits, the BMidiRoster instance isdestroyed by the BMidiRosterKiller. The BMidiRosterLooper is alsodestroyed, along with any endpoint objects from its list. We don'tdestroy endpoints with a refcount > 0, but print a warning message onstderr instead.- When the app quits before it has created a BMidiRoster instance, theBMidiRosterKiller should do nothing.--------------Creating endpoints------------------*Required:* Client app that creates a new BMidiLocalProducer and/orBMidiLocalConsumer- Send invalid Mnew message (missing fields). The server will return anerror code.- Don't send reply from midi_server. The client receives a B_NO_REPLYerror.- If something goes wrong creating a new local endpoint, you still geta new BMidiEndpoint object (but it is not added toBMidiRosterLooper's internal list of endpoints). Verify that its ID()function returns 0, and IsValid() returns false. Verify that you canRelease() it without crashing into the debugger (i.e. the referencecount of the new object should be 1).- Snooze in midi_server's OnCreateEndpoint() before sending reply toclient to simulate heavy processor load. Client should timeout. Whendone snoozing, server fails to deliver the reply because the clientis no longer listening, and it unregisters the app.- Note: if you kill the client app with Ctrl-C before the server hassent its reply, SendReply() still returns okay, and the midi_serveradds the endpoint, even though the corresponding app is dead. Thereis not much we can do to prevent that (but it is not really a bigdeal).- Start the test app from two different Terminals. Verify that the newlocal endpoint of app1 is added to the BMidiRosterLooper's list ofendpoints, and that its "isLocal" flag is true. Verify that when youstart the second app, it immediately receives mNEW notifications forthe first app's endpoints. It should also create BMidiEndpoint proxyobjects for these endpoints with "isLocal" set to false, and add themits own list. Vice versa for the endpoints that app2 creates. Verifythat the "registered" field in the mNEW notification is false,because newly created endpoints are not registered yet. The"properties" field should contain an empty message.- Start server. Start client app. The app makes new endpoints and theserver adds them to the roster. Ctrl-C the app. Start client appagain. The new client first receives mNEW notifications for the oldapp's endpoints. When the new app tries to create its own endpoints,the server realizes that the old app is dead, and sends mDELnotifications for the now-defunct endpoints.- The test app should now create 2 endpoints. Let the midi_serversnooze during the second create message, so the app times out. Theserver now unregisters the app and purges its first endpoint (whichwas successfully created).- The test app should now create 3 endpoints. Let the midi_serversnooze during the second create message, so the app times out. (Italso times out when sending the create request for the 3rd endpoint,because the server is still snoozing.) Because it cannot send a replyfor the 2nd create message, the server now unregisters the app andpurges its first endpoint (which was successfully created). Then itprocesses the create request for the 3rd endpoint, but ignores itbecause the app is now no longer registered with the server.- Purging endpoints. The test app should now create 2 endpoints. Letthe midi_server snooze during the \_fourth\_ create message. Run theserver. Run the test app. Run the test app again in a secondTerminal. The server times out, and unregisters the second app. Thefirst app should receive an mDEL notification. Repeat, but now thetest app should make 3 endpoints and the server fails on the\_sixth\_ endpoint. The first app now receives 2 mDEL notifications.- You should be allowed to pass NULL into the BMidiLocalProducer andBMidiLocalConsumer constructor.- Let the midi_server assign random IDs to new endpoints; theBMidiRosterLooper should sort the endpoints by their IDs when it addsthem to its internal list.--------------Deleting endpoints------------------*Required:* client app that creates one or more endpoints andRelease()'s them- Verify that Acquire() increments the endpoint's refcount andRelease() decrements it. When you Release() a local endpoint so itsrefcount becomes zero, the client sends an Mdel request to theserver. When you Release() a local endpoint too many times, your appjumps into the debugger.- Send an Mdel request with an invalid ID to the server. Examples ofinvalid IDs: -1, 0, 1000 (or any other large number).- Start the test app from two different Terminals. Note that when oneof the apps Release()'s its endpoints, the other receivescorresponding mDEL notifications.- Snooze in midi_server's OnCreateEndpoint() before sending reply to"create endpoint" request. The client will timeout and the serverwill unregister the app. Now have the client Release() the endpoint.This sends a "delete endpoint" request to the server, which ignoresthe request because the app is no longer registered.- Override BMidiLocalProducer and BMidiLocalConsumer, and provide apublic destructor. Call "delete prod; delete cons;" from your code,instead of using Release(). Your app should drop into the debugger.- Start the client app and let it make its endpoints. Kill the server.Release() the endpoints. The server doesn't run, so the Mdel requestnever arrives, but the BMidiEndpoint objects should be deletedregardless.- Start the test app from two different Terminals, and let them maketheir endpoints. Quit the apps (using the Deskbar's "QuitApplication" menu item). Verify that both clean up and exitcorrectly. App1 removes its own endpoint from the BMidiRosterLooper'slist of endpoints and sends an 'mDEL' message to the server, whichpasses it on to app2. In response, app2 removes the proxy object fromits own list and deletes it. Again, vice versa for the endpoint fromapp2.- Start both apps again and wait until they have notified each otherabout the endpoints. Ctrl-C app1, and restart it. Verify that app1receives the 'mNEW' messages and creates proxies for these remoteendpoints. Both apps should receive an 'mDEL' message for app1's oldendpoint (because the midi_server realizes it no longer exists andpurges it), and remove it from their lists accordingly.--------------Changing attributes-------------------*Required:* Client app that creates an endpoint and calls Register(),Unregister(), SetName(), and SetLatency()- Send an Mchg request with an invalid ID to the server.- Register() a local endpoint that is already registered. This does notsend a message to the server and always returns B_OK. Likewise forUnregister()ing a local endpoint that is not registered.- Register() or Unregister() a remote endpoint, or an invalid localendpoint. That should immediately return an error code.- Verify that BMidiRoster::Register() does the same thing asBMidiEndpoint::Register(). Also for BMidiRoster::Unregister() andBMidiEndpoint::Unregister().- If you pass NULL into BMidiRoster::Register() or Unregister(), thefunctions immediately return with an error code.- SetName() should ignore NULL names. When you call it on a remoteendpoint, SetName() should do nothing. SetName() does not send amessage if the new name is the same as the current name.- SetLatency() should ignore negative values. SetLatency() does notsend a message if the new latency is the same as the current latency.(Since SetLatency() lives in BMidiLocalConsumer, you can never use iton remote endpoints.)- Kill the server after making the new endpoint, and call Register().The client app should return an error code. Also for Unregister(),SetName(), SetLatency(), and SetProperties().- Snooze in the midi_server's OnChangeEndpoint() before sending thereply to the client. Both sides will flag an error. No mCHGnotifications will be sent. The server unregisters the app and purgesits endpoints.- Verify that other apps will receive mCHG notifications when the testapp successfully calls Register(), Unregister(), SetName(), andSetLatency(), and that they modify the corresponding BMidiEndpointobjects accordingly. Since clients are never notified when theychange their own endpoints, they should ignore the notifications thatconcern local endpoints. Latency changes should be ignored if theendpoint is not a consumer.- Send an Mchg request with only the "midi:id" field, so no"midi:name", "midi:registered", "midi:latency", or "midi:properties".The server will still notify the other apps, although they willobviously ignore the notification, because it doesn't contain anyuseful data.- The Mchg request is overloaded to change several attributes. Verifythat changing one of these attributes, such as the latency, does notoverwrite/wipe out the others.- Start app1. Wait until it has created and registered its endpoint.Start app2. During the initial handshake, app2 should receive an'mNEW' message for app1's endpoint. Verify that the "refistered"field in this message is already true, and that this is passed oncorrectly to the new BMidiEndpoint proxy object.- GetProperties() should return NULL if the message parameter is NULL.- The properties of new endpoints are empty. Create a new endpoint andcall GetProperties(). The BMessage that you receive should contain nofields.- SetProperties() should return NULL if the message parameter is NULL.It should return an error code if the endpoint is remote or invalid.It should work fine on local endpoints, registered or not.SetProperties() does not compare the contents of the new BMessage tothe old, so it will always send out the change request.- If you Unregister() an endpoint that is connected, the connectionshould not be broken.--------------Consulting the roster---------------------*Required:* Client app that creates several endpoints, and registerssome of them (not all), and uses the BMidiRoster::FindEndpoint() etcfunctions to examine the roster.- Verify that FindEndpoint() returns NULL if you pass it:- invalid ID (localOnly = false)- invalid ID (localOnly = true)- remote non-registered endpoint (localOnly = false)- remote non-registered endpoint (localOnly = true)- remote registered endpoint (localOnly = true)|Verify that FindEndpoint() returns a valid BMidiEndpoint object ifyou pass it:- local non-registered endpoint (localOnly = false)- local non-registered endpoint (localOnly = true)- local registered endpoint (localOnly = false)- local registered endpoint (localOnly = true)- remote registered endpoint (localOnly = false)|- Verify that FindConsumer() works just like FindEndpoint(), but thatit also returns NULL if the endpoint with the specified ID is not aconsumer. Likewise for FindProducer().- Verify that NextEndpoint() returns NULL if you pass it NULL. It alsoreturns NULL if no more endpoints exist. Otherwise, it returns aBMidiEndpoint object, bumps the endpoint's reference count, and setsthe "id" parameter to the ID of the endpoint. NextEndpoint() shouldnever return local endpoints (registered or not), nor unregisteredremote endpoints. Verify that negative "id" values also work.- Verify that you can safely call the Find and Next functions withouthaving somehow initialized the BMidiRoster first (by making a newendpoint, for example). The functions themselves should callMidiRoster() and do the handshake with the server.- The Find and Next functions should bump the reference count of theBMidiEndpoint object that they return. However, they should not(inadvertently) modify the refcounts of any other endpoint objects.- Get a BMidiEndpoint proxy for a remote published endpoint. Release().Now it should not be removed from the endpoint list or even bedeleted, even though its reference count dropped to zero.- Start app1. Start app2. App2 gets a BMidiEndpoint proxy for a remoteendpoint from app1. Ctrl-C app1. Start app1 again. Now app2 receivesan mDEL message for app1's old endpoint. Verify that the endpoint isremoved from the endpoint list, but not deleted because its referencecount isn't zero. If app2 now Release()s the endpoint, theBMidiEndpoint object should be deleted. Try again, but now Release()the endpoint before you Ctrl-C; now it should be deleted and removedfrom the list when you start app1 again.--------------Making/breaking connections---------------------------*Required:* Client app that creates a producer and consumer endpoint,optionally registers them, consults the roster for remote endpoints, andmakes various kinds of connections.- Test the following for BMidiProducer::Connect():- Connect(NULL)- Connect(invalid consumer)- Connect() using an invalid producer- Send Mcon request with invalid IDs- Kill the midi_server just before you Connect()- Let the midi_server snooze, so the connect request times out- Have the midi_server return an error result code- On successful connect, verify that the consumer is added to theproducer's list of endpoints- Verify that you can make connections between 2 local endpoints, alocal producer and a remote consumer, a remote producer and alocal consumer, and two 2 remote endpoints. Test the localendpoints both registered and unregistered.- 2x Connect() on same consumer should give an error- The other applications should receive an mCON notification, andadjust their own local rosters accordingly- If you are calling Connect() on a local producer, its Connected()hook should be called. If you are calling Connect() on a remoteproducer, then its own application should call the Connected()hook.|- Test the following for BMidiProducer::Disconnect():- Disconnect(NULL)- Disconnect(invalid consumer)- Disconnect() using an invalid producer- Send Mdis request with invalid IDs- Kill the midi_server just before you Disconnect()- Let the midi_server snooze, so the disconnect request times out- Have the midi_server return an error result code- On successful disconnect, verify that the consumer is removed fromthe producer's list of endpoints- Verify that you can break connections between 2 local endpoints, alocal producer and a remote consumer, a remote producer and alocal consumer, and two 2 remote endpoints. Test the localendpoints both registered and unregistered.- Disconnecting 2 endpoints that were not connected should give anerror- The other applications should receive an mDIS notification, andadjust their own local rosters accordingly- If you are calling Disconnect() on a local producer, itsDisconnected() hook should be called. If you are callingDisconnect() on a remote producer, then its own application shouldcall the Disconnected() hook.|- Make a connection on a local producer. Release() the producer. Theother app should only receive an mDEL notification. Likewise if youhave a connection with a local consumer and you Release() that.However, now all apps should throw away this consumer from theconnection lists, invoking the Disconnected() hook of localproducers. The same thing happens if you Ctrl-C the app and restartit. (Now the old endpoints are purged.)- BMidiProducer::IsConnected() should return false if you pass NULL oran invalid consumer.- BMidiProducer::Connections() should return a new BList every time youcall it. The objects in this list are the BMidiConsumers that areconnected to this producer; verify that their reference counts arebumped for every call to Connections().--------------Watching--------*Required:* Client app that creates local consumer and producerendpoints, and calls Register(), Unregister(), SetName(), SetLatency(),and SetProperties(). It should also make and break connections.- When you call StartWatching(), you should receive B_MIDI_EVENTnotifications for all remote registered endpoints and the connectionsbetween them. You will get no notifications for local endpoints, orfor any connections that involve unregistered endpoints. TheBMidiRosterLooper should make a copy of the BMessenger, so when theclient destroys the original messenger, you will still receivenotifications. Verify that calling StartWatching() with the sameBMessenger twice in a row will also send the initial set ofnotifications twice. StartWatching(NULL) should be ignored and doesnot remove the current messenger.- Run the client app from two different Terminals. Verify that youreceive properly formatted B_MIDI_EVENT notifications when the otherapp changes the attributes of its *registered* endpoints with thevarious Set() functions. You should also receive notifications if theapp Register()s or Unregister()s its endpoints. That app that makesthese changes does not receive the notifications.- Run the client app from two different Terminals. Verify that youreceive properly formatted B_MIDI_EVENT notifications when the appsmake and break connections. Every app receives these connectionnotifications, whether the endpoints are published or not. The appthat makes and breaks the connections does not receive anynotifications.- StopWatching() should delete BMidiRosterLooper's BMessenger copy, ifany. Verify that you no longer receive B_MIDI_EVENT notifications forremote endpoints after you have called StopWatching().- If the client is watching, and the BMidiRosterLooper receives an mDELnotification for a registered remote endpoint, it should also send an"unregistered" B_MIDI_EVENT to let the client know that this endpointis no longer available. If the endpoint was connected to anything,you'll also receive "disconnected" B_MIDI_EVENTs.- If you get a "registered" event, and you do FindEndpoint() for thatid, you'll get its BMidiEndpoint object. If you get an "unregistered"event, then FindEndpoint() returns NULL. So the events are send*after* the roster is modified.--------------Event tests-----------*Required:* Several client apps that create and register consumerendpoints that override the various MIDI event hook functions, as wellas producer endpoints that spray MIDI events. Also useful is a tool thatlets you make connections between all these endpoints (PatchBay), and atool that lets you monitor the MIDI events (MidiMonitor).- BMidiLocalProducer's spray functions should only try to sendsomething if there is one or more connected consumer. If the sprayfunctions cannot deliver their events, they simply ignore thatconsumer until the next spray. (No connections are broken oranything.)- All spray functions except SprayData() should set the atomic flag totrue, even SpraySystemExclusive().- When you send a sysex message using SpraySystemExclusive(), it shouldadd 0xF0 in front of your data and 0xF7 at the back. When you callSprayData() instead, no bytes are added to the MIDI event data.- Verify that all events arrive correctly and that the latency isminimal, even when the load is heavy (i.e. many events are beingsprayed to many different consumers).- Verify that the BMidiLocalConsumer destructor properly destroys thecorresponding port and event thread before it returns.- BMidiLocalConsumer should ignore messages that are too small,addressed to another consumer, or otherwise invalid.- BMidiLocalConsumer's Data() hook should ignore all non-atomic events.The rest of the events, provided they contain the correct number ofbytes for that kind of event, are passed on to the other hooks.- Hook a producer up to a consumer and call all SprayXXX() functionswith a variety of arguments to make sure the correct hooks are beingcalled with the correct values. Call SprayData() andSpraySystemExclusive() with NULL data and/or length 0.- Call GetProducerID() from one of BMidiLocalConsumer's hooks to verifythat this indeed returns the ID of the producer that sprayed theevent.- To test timeouts, first call SetTimeout(system_time() + 2000000),spray an event to the consumer, and wait 2 seconds. The consumer'sTimeout() hook should now be called. Try again, but now spraymultiple events to the consumer. The Timeout() hook should still becalled after 2 seconds, measured from the moment the timeout was set.Replace the call to SetTimeout() with SetTimeout(0). After sprayingthe first event, you should immediately get the Timeout() signal,because the target time was set in the past. Verify that callingSetTimeout() only takes effect after at least one new event has beenreceived.--------------Other tests------------ Kill the server. Now run a client app. It should recognize that theserver isn't running, and return error codes on all operations. Alsokill the server while the test app is running. From then on, theclient app will return error codes on all operations. Also bring itback up again while the test app is still running. Now the clientapp's request messages will be delivered to the server again, but theserver will ignore them, because our app did not register with thisnew instance of the server.- Start the midi_server and several client apps. Use PatchBay to makeand break a whole bunch of connections. Quit PatchBay. Start itagain. Now the same connections should show up. Run similar testswith MidiKeyboard. Also install VirtualMidi (and run the oldmidi_server for the time being) to get a whole bunch of fake MIDIdevices.- *Regression bug:* After you quit one client app, another app fails tosend request to the midi_server.*Required:* Client app that creates a new endpoint and registers it.In the app's destructor, it unregisters and releases the endpoint.*How to reproduce:* Run the app from two different Terminals. Ctrl-Capp1. Start app1 again. From the Deskbar quit both apps at the sametime (that is possible because app1 and app2 both have the samesignature). When it tries to send the Unregister() request to themidi_server, app2 gives the error "Cannot send msg to server". Theerror code is "Bad Port ID", which means that the reply port is dead.The Mdel message from Release() is sent without any problems,however, because that expects no reply back. This is not the only wayto reproduce the problem, but it seems to be the most reliable one.The reason this happens is because you kill app1. When app2 sends asynchronous request to the midi_server, the server re-used that samemessage to notify the other apps. (Because it already contained allthe necessary fields.) But app1 is dead, the notification fails, andthis (probably) wipes out the reply address in the message. I changedthe midi_server to create new BMessages for the notifications, andwas no longer able to reproduce the problem.