/* CommandInstanceManager(Test) - verify helper for setup of actual command definitions Copyright (C) 2017, Hermann Vosseler   **Lumiera** is free software; you can redistribute it and/or modify it   under the terms of the GNU General Public License as published by the   Free Software Foundation; either version 2 of the License, or (at your   option) any later version. See the file COPYING for further details. * *****************************************************************/ /** @file command-instance-manager-test.cpp ** unit test \ref CommandInstanceManager_test */ #include "lib/test/run.hpp" #include "steam/control/test-dummy-commands.hpp" #include "steam/control/command-instance-manager.hpp" #include "lib/format-string.hpp" #include "lib/format-cout.hpp" #include "lib/iter-stack.hpp" #include "lib/util.hpp" #include #include #include #include namespace steam { namespace control { namespace test { using lib::Literal; using std::string; using util::_Fmt; using std::move; using LERR_(LIFECYCLE); using LERR_(INVALID_COMMAND); using LERR_(DUPLICATE_COMMAND); using LERR_(UNBOUND_ARGUMENTS); namespace { // Test fixture.... const Symbol COMMAND_PROTOTYPE = test_Dummy_command1; const string INVOCATION_ID = "CommandInstanceManager_test"; class Fixture : public CommandDispatch { std::deque queue_; /* == Interface: CommandDispatch == */ void clear() override { queue_.clear(); } void enqueue (Command&& cmd) override { queue_.emplace_front (move (cmd)); } public: bool contains (Command const& ref) { return queue_.end()!= std::find_if (queue_.begin() ,queue_.end() ,[=](Command const& elm) { return elm == ref; }); } void invokeAll() { for (Command& cmd : queue_) cmd(); clear(); } }; } /***********************************************************************//** * @test CommandInstanceManager is responsible for providing individual * clone copies from a basic command definition, to be bound with * actual arguments and finally handed over to the SteamDispatcher * for invocation. * * @see steam::control::CommandInstanceManager */ class CommandInstanceManager_test : public Test { virtual void run (Arg) { seedRand(); verify_simpleUsage(); verify_extendedUsage(); verify_instanceIdentity(); verify_duplicates(); verify_lifecycle(); verify_fallback(); } /** @test demonstrate the transparent instance generation (»fire and forget«) * - when just specifying a global commandID and arguments, an anonymous * instance will be created on-the-fly, bound and dispatched, without * leaving any traces in the global or local registry * - when dispatching a global commandID, where the corresponding * prototype entry is already fully bound and ready for execution, * likewise an anonymous clone copy is created and dispatched. * @remarks these simplified use cases cover a large fraction of all usages, * and most notably, the internal registry embedded within the * CommandInstanceManager won't be used at all. */ void verify_simpleUsage() { Fixture fixture; CommandInstanceManager iManager{fixture}; CHECK (not iManager.contains (COMMAND_PROTOTYPE)); int r1{rani(1000)}, r2{rani(2000)}; command1::check_ = 0; // commands will add to this on invocation iManager.bindAndDispatch (COMMAND_PROTOTYPE, Rec{r1}); CHECK (not iManager.contains (COMMAND_PROTOTYPE)); Command com{COMMAND_PROTOTYPE}; com.bind(r2); CHECK (com.canExec()); iManager.dispatch (COMMAND_PROTOTYPE); CHECK (not iManager.contains (COMMAND_PROTOTYPE)); // an anonymous clone instance was dispatched, // thus re-binding the arguments won't interfere with execution com.bind(-1); CHECK (command1::check_ == 0); // nothing invoked yet fixture.invokeAll(); CHECK (command1::check_ == r1 + r2); // both instances were invoked with their specific arguments // clean-up: we have bound arguments on the global prototype com.unbind(); } /** @test demonstrate the complete command instance usage pattern.*/ void verify_extendedUsage() { Fixture fixture; CommandInstanceManager iManager{fixture}; Symbol instanceID = iManager.newInstance (COMMAND_PROTOTYPE, INVOCATION_ID); CHECK (iManager.contains (instanceID)); Command cmd = iManager.getInstance (instanceID); CHECK (cmd); CHECK (not cmd.canExec()); cmd.bind(42); CHECK (cmd.canExec()); iManager.dispatch (instanceID); CHECK (fixture.contains (cmd)); CHECK (not iManager.contains (instanceID)); VERIFY_ERROR (LIFECYCLE, iManager.getInstance (instanceID)); command1::check_ = 0; fixture.invokeAll(); CHECK (command1::check_ == 42); // the dispatched instance was executed } /** @test relation of command, instanceID and concrete instance * The CommandInstanceManager provides the notion of a _current instance,_ * which can then be used to bind arguments. When done, it will be _dispatched,_ * and then go through the SteamDispatcher's CommandQueue (in this test, we use * just a dummy Fixture, which only enqueues the dispatched commands. * * The following notions need to be kept apart * - a *command* is the operation _definition_. It is registered with a commandID. * - the *instance ID* is a decorated commandID and serves to keep different * usage contexts of the same command (prototype) apart. For each instanceID * there is at any given time maximally _one_ concrete instance "opened" * - the *concrete command instance* is what can be bound and executed. * It retains it's own identity, even after being handed over for dispatch. * Consequently, a given instance can sit in the dispatcher queue to await * invocation, while the next instance for the _same instance ID_ is already * opened in the CommandInstanceManager for binding arguments. */ void verify_instanceIdentity() { Fixture fixture; CommandInstanceManager iManager{fixture}; Symbol i1 = iManager.newInstance (COMMAND_PROTOTYPE, "i1"); Symbol i2 = iManager.newInstance (COMMAND_PROTOTYPE, "i2"); Command c11 = iManager.getInstance (i1); Command c12 = iManager.getInstance (i1); CHECK (c11 == c12); CHECK (c11.isValid()); CHECK (not c11.canExec()); int r1{rani(100)}, r2{rani(200)}, r3{rani(300)}; command1::check_ = 0; // commands will add to this on invocation c11.bind (r1); CHECK (c12.canExec()); CHECK (c11.canExec()); Command c2 = iManager.getInstance (i2); CHECK (c2 != c11); CHECK (c2 != c12); c2.bind (r2); CHECK (iManager.contains (i1)); CHECK (iManager.contains (i2)); CHECK (not fixture.contains (c11)); CHECK (not fixture.contains (c12)); CHECK (not fixture.contains (c2)); iManager.dispatch (i1); CHECK (not iManager.contains (i1)); CHECK ( iManager.contains (i2)); CHECK ( fixture.contains (c11)); CHECK ( fixture.contains (c12)); CHECK (not fixture.contains (c2)); CHECK (command1::check_ == 0); Symbol i11 = iManager.newInstance (COMMAND_PROTOTYPE, "i1"); CHECK (i11 == i1); CHECK (CStr(i11) == CStr(i1)); // but the instances themselves are disjoint Command c13 = iManager.getInstance (i1); CHECK (c13 != c11); CHECK (c13 != c12); CHECK (c11.canExec()); CHECK (not c13.canExec()); c13.bind (r3); CHECK (c13.canExec()); CHECK (command1::check_ == 0); c12(); CHECK (command1::check_ == 0+r1); // even a command still in instance manager can be invoked c2(); CHECK (command1::check_ == 0+r1+r2); CHECK ( iManager.contains (i1)); CHECK ( iManager.contains (i2)); CHECK ( fixture.contains (c11)); CHECK ( fixture.contains (c12)); CHECK (not fixture.contains (c2)); iManager.dispatch (i2); iManager.dispatch (i11); CHECK (not iManager.contains (i1)); CHECK (not iManager.contains (i2)); CHECK ( fixture.contains (c11)); CHECK ( fixture.contains (c12)); CHECK ( fixture.contains (c13)); CHECK ( fixture.contains (c2)); // if we continue to hold onto an instance, // we can do anything with it. Like re-binding arguments. c2.bind (47); c2(); c13(); c13(); CHECK (command1::check_ == 0+r1+r2+47+r3+r3); c11.undo(); CHECK (command1::check_ == 0); c2.undo(); CHECK (command1::check_ == 0+r1+r2); // undo() restores the value captured before second invocation of c2() c12.undo(); // c11 and c12 refer to the same instance, which was invoked first CHECK (command1::check_ == 0); } /** @test there can be only one active "opened" instance * The CommandInstanceManager opens (creates) a new instance by cloning from the prototype. * Unless this instance is dispatched, it does not allow to open a further instance * (for the same instanceID). But of course it allows to open a different instance from * the same prototype, but with a different invocationID and hence a different instanceID */ void verify_duplicates() { Fixture fixture; CommandInstanceManager iManager{fixture}; Symbol i1 = iManager.newInstance (COMMAND_PROTOTYPE, "i1"); Symbol i2 = iManager.newInstance (COMMAND_PROTOTYPE, "i2"); VERIFY_ERROR (DUPLICATE_COMMAND, iManager.newInstance (COMMAND_PROTOTYPE, "i1")); VERIFY_ERROR (DUPLICATE_COMMAND, iManager.newInstance (COMMAND_PROTOTYPE, "i2")); iManager.bindAndDispatch (i1, {-1}); // bind and dispatch i1, thus i1 is ready for new cycle iManager.newInstance (COMMAND_PROTOTYPE, "i1"); // open new cycle for i1 VERIFY_ERROR (DUPLICATE_COMMAND, iManager.newInstance (COMMAND_PROTOTYPE, "i2")); CHECK (iManager.getInstance (i1)); CHECK (iManager.getInstance (i2)); } /** @test verify sane command lifecycle is enforced * - instance need to be opened (created) prior to access * - can not dispatch an instance not yet created * - can not create new instance before dispatching the existing one * - can not dispatch an instance before binding its arguments * - can not access an instance already dispatched */ void verify_lifecycle() { Fixture fixture; CommandInstanceManager iManager{fixture}; // a manually constructed ID is unknown of course Symbol instanceID{COMMAND_PROTOTYPE, INVOCATION_ID}; VERIFY_ERROR (INVALID_COMMAND, iManager.getInstance (instanceID)); VERIFY_ERROR (INVALID_COMMAND, iManager.dispatch (instanceID)); Symbol i2 = iManager.newInstance (COMMAND_PROTOTYPE, INVOCATION_ID); CHECK (i2 == instanceID); CHECK (iManager.getInstance (instanceID)); Command cmd = iManager.getInstance (instanceID); CHECK (cmd); CHECK (not cmd.canExec()); VERIFY_ERROR (UNBOUND_ARGUMENTS, iManager.dispatch (instanceID)); VERIFY_ERROR (DUPLICATE_COMMAND, iManager.newInstance (COMMAND_PROTOTYPE, INVOCATION_ID)); CHECK (iManager.contains (instanceID)); // errors have not messed up anything cmd.bind(23); CHECK (cmd.canExec()); iManager.dispatch (instanceID); CHECK (not iManager.contains (instanceID)); VERIFY_ERROR (LIFECYCLE, iManager.getInstance (instanceID)); VERIFY_ERROR (LIFECYCLE, iManager.dispatch (instanceID)); CHECK (instanceID == iManager.newInstance (COMMAND_PROTOTYPE, INVOCATION_ID)); } /** @test the instance manager automatically falls back on globally registered commands, * when the given ID is not and was not known locally */ void verify_fallback() { Fixture fixture; CommandInstanceManager iManager{fixture}; CHECK (not iManager.contains (COMMAND_PROTOTYPE)); Command cmd = iManager.getInstance (COMMAND_PROTOTYPE); CHECK (cmd.isValid()); CHECK (not cmd.isAnonymous()); CHECK (cmd == Command::get(COMMAND_PROTOTYPE)); CHECK (cmd == Command{COMMAND_PROTOTYPE}); cmd.bind(-12); CHECK (cmd.canExec()); CHECK (not fixture.contains(cmd)); iManager.dispatch (COMMAND_PROTOTYPE); CHECK (fixture.contains(cmd)); // an equivalent clone was enqueued command1::check_ = 0; fixture.invokeAll(); CHECK (command1::check_ == -12); // the clone copy was executed // clean-up: we have bound arguments on the global prototype cmd.unbind(); } }; /** Register this test class... */ LAUNCHER (CommandInstanceManager_test, "unit controller"); }}} // namespace steam::control::test