Test.h

/*
MIT License
 
Copyright (c) 2018 Brian T. Park
 
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
 
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
 
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
*/
 
// Significant portions of the design and implementation of this file came from
// https://github.com/mmurdoch/arduinounit/blob/master/src/ArduinoUnit.h
 
#ifndef AUNIT_TEST_H
#define AUNIT_TEST_H
 
#include <stdint.h>
#include "FCString.h"
#include "Verbosity.h"
 
namespace aunit {
 
class Test {
  public:
    // The LifeCycle states are used by TestRunner to determine what a Test
    // should do. Unlike the assertion Status, the LfeCycle is mostly hidden
    // from client code. The state transition diagram looks like this:
    //
    //        include()/exclude()
    //      .---------------------> Excluded -----------.
    //      v                                           v
    //    New                                        Finished -> (out of list)
    //      \ setup()      assertion()       teardown() ^
    //       -------> Setup -------> Asserted ----------'
 
    static const uint8_t kLifeCycleNew = 0;
 
    static const uint8_t kLifeCycleExcluded = 1;
 
    static const uint8_t kLifeCycleSetup = 2;
 
    static const uint8_t kLifeCycleAsserted = 3;
 
    static const uint8_t kLifeCycleFinished = 4;
 
    // The assertion Status is the result of an "assertion()". In addition to
    // the usual pass() and fail(), there are meta-assertions such as skip()
    // and expire(). When the Status is changed from kStatusUnknown, the
    // lifeCycle state changes to kLifeCycleAsserted.
 
    static const uint8_t kStatusUnknown = 0;
 
    static const uint8_t kStatusPassed = 1;
 
    static const uint8_t kStatusFailed = 2;
 
    static const uint8_t kStatusSkipped = 3;
 
    static const uint8_t kStatusExpired = 4;
 
    static Test** getRoot();
 
    Test();
 
    // NOTE: Don't create a virtual destructor. That's the normal best practice
    // for classes that will be used polymorphically. However, this class will
    // never be deleted polymorphically (i.e. through its pointer) so it
    // doesn't need a virtual destructor. In fact, adding it causes flash and
    // static memory to increase dramatically because each test() and testing()
    // macro creates a new subclass. AceButtonTest flash memory increases from
    // 18928 to 20064 bytes, and static memory increases from 917 to 1055
    // bytes.
 
    virtual void setup() {}
 
    virtual void teardown() {}
 
    virtual void loop() = 0;
 
    void resolve();
 
    const internal::FCString& getName() const { return mName; }
 
    uint8_t getLifeCycle() const { return mLifeCycle; }
 
    void setLifeCycle(uint8_t state) { mLifeCycle = state; }
 
    uint8_t getStatus() const { return mStatus; }
 
    void setStatus(uint8_t status) {
      if (status != kStatusUnknown) {
        setLifeCycle(kLifeCycleAsserted);
      }
      mStatus = status;
    }
 
    void setPassOrFail(bool ok);
 
    Test** getNext() { return &mNext; }
 
    bool isDone() const { return mStatus != kStatusUnknown; }
 
    bool isNotDone() const { return !isDone(); }
 
    bool isPassed() const { return mStatus == kStatusPassed; }
 
    bool isNotPassed() const { return !isPassed(); }
 
    bool isFailed() const { return mStatus == kStatusFailed; }
 
    bool isNotFailed() const { return !isFailed(); }
 
    bool isSkipped() const { return mStatus == kStatusSkipped; }
 
    bool isNotSkipped() const { return !isSkipped(); }
 
    bool isExpired() const { return mStatus == kStatusExpired; }
 
    bool isNotExpired() const { return !isExpired(); }
 
    void skip() { setStatus(kStatusSkipped); }
 
    void expire() { setStatus(kStatusExpired); }
 
    void enableVerbosity(uint8_t verbosity) { mVerbosity |= verbosity; }
 
    void disableVerbosity(uint8_t verbosity) { mVerbosity &= ~verbosity; }
 
  protected:
    void fail() { setStatus(kStatusFailed); }
 
    void pass() { setStatus(kStatusPassed); }
 
    void init(const char* name) {
      mName = internal::FCString(name);
      mLifeCycle = kLifeCycleNew;
      mStatus = kStatusUnknown;
      mVerbosity = 0;
      insert();
    }
 
    void init(const __FlashStringHelper* name) {
      mName = internal::FCString(name);
      mLifeCycle = kLifeCycleNew;
      mStatus = kStatusUnknown;
      mVerbosity = 0;
      insert();
    }
 
    bool isVerbosity(uint8_t verbosity) const { return mVerbosity & verbosity; }
 
    uint8_t getVerbosity() const { return mVerbosity; }
 
  private:
    // Disable copy-constructor and assignment operator
    Test(const Test&) = delete;
    Test& operator=(const Test&) = delete;
 
    void insert();
 
    internal::FCString mName;
    uint8_t mLifeCycle;
    uint8_t mStatus;
    uint8_t mVerbosity;
    Test* mNext;
};
 
}
 
#endif