<?php
/**
 * unit tests for the read broker using PDO data class
 *
 * each test block has relative comments
 *
 * Note:  A lot of these tests are closely-duplicated from the tests in readBrokerMongoTest.php which is as it should
 * be as the framework purports to be schema-agnostic... using duplicated tests (I've tweaked some values for templates
 * and fields because we're working with a different test-class) should, by intent and design, prove this to be true.
 *
 * Note:  queries will increase in complexity starting with a simple select and then eventually ending up with a query
 * similar (or identical) to:
 *
 * SELECT createdDate_tst, count(*), status_tst, testInteger_tst
 * FROM gaTest_tst
 * GROUP BY testInteger_tst
 * HAVING testBoolean_tst = 1
 * ORDER BY createdDate_tst DESC
 *
 *
 * @author  mike@givingassistant.org
 * @version 1.0
 *
 * HISTORY:
 * ========
 * 10-11-17     mks     CORE-584: original coding
 * 01-17-19     mks     DB-105: updated for audit testing support
 * 03-13-19     mks     DB-116: updated for the new cacheMapping
 *
 */

$_REDIRECT = false;
require(dirname(__DIR__) . '/../config/sneakerstrap.inc');       // and load the namaste environment

use PHPUnit\Framework\TestCase;

class readBrokerPDOTest extends TestCase
{
    protected ?gacBrokerClient $readBrokerClient;
    protected ?gacBrokerClient $adminOutClient;
    protected static ?array $meta;
    protected static ?array $adminMeta;
//    protected static $keys;
    protected static int $maxRecordCount;
    protected static int $totalRecordCount;
    protected static string $dataKey;
    protected static string $eventKey;

    /**
     * setUpBeforeClass() -- public static unit test method
     *
     * this method is called first, and once, on execution.  It sets up a list of brokers we're going to test.
     *
     * @author  mike@givingassistant.org
     * @version 1.0
     *
     *
     * HISTORY:
     * ========
     * 10-11-17     mks     original coding
     *
     */
    public static function setUpBeforeClass()
    {
        parent::setUpBeforeClass();

        // meta data
        static::$meta = [
            META_CLIENT => CLIENT_UNIT,
            META_CLIENT_IP => STRING_SESSION_HOME,
            META_SYSTEM_NOTES => STRING_ORIGIN_UT,
            META_TEMPLATE => TEMPLATE_CLASS_TEST_PDO
        ];

        // meta data for admin requests
        static::$adminMeta = [
            META_CLIENT => CLIENT_UNIT,
            META_CLIENT_IP => STRING_SESSION_HOME,
            META_SYSTEM_NOTES => STRING_ORIGIN_UT
        ];

        // max record count
        static::$maxRecordCount = gasConfig::$settings[CONFIG_DATABASE][CONFIG_DATABASE_QUERY_RECORD_LIMIT];
    }


    /**
     * setUp() -- unit test reserved method
     *
     * the setUp method is executed prior to each test - the method instantiates a new client connecting to the
     * read broker.
     *
     * @author  mike@givingassistant.org
     * @version 1.0
     *
     *
     * HISTORY:
     * ========
     * 10-11-17     mks     CORE:584: original coding
     * 01-17-19     mks     DB-105: support for audit/journal testing
     *
     */
    protected function setUp()
    {
        // validate the meta data for the pending query
        $this->assertTrue(!empty(static::$meta), (__FILE__ . COLON . __LINE__) . COLON . ERROR_DATA_META_404);
        $this->assertTrue(is_array(static::$meta), (__FILE__ . COLON . __LINE__) . COLON . ERROR_META_INVALID_FORMAT_ARRAY);
        $this->assertTrue(array_key_exists(META_TEMPLATE, static::$meta), (__FILE__ . COLON . __LINE__) . COLON . ERROR_DATA_META_KEY_404 . META_TEMPLATE);

        $this->readBrokerClient = new gacBrokerClient(BROKER_QUEUE_R, basename(__FILE__) . COLON . __METHOD__ . COLON . __LINE__);
        $this->assertTrue($this->readBrokerClient->status, __METHOD__ . __LINE__ . ERROR_BROKER_QUEUE_DECLARE . BROKER_QUEUE_R);

        // create the admin broker client
        $this->adminOutClient = new gacBrokerClient(BROKER_QUEUE_AO, basename(__FILE__) . COLON . __METHOD__ . COLON . __LINE__);
        $this->assertTrue($this->adminOutClient->status, __FILE__ . COLON . __LINE__ . COLON . ERROR_BROKER_QUEUE_DECLARE . BROKER_QUEUE_AO);
    }


    /**
     * tearDown() -- unit test method
     *
     * this is the (reserved) tearDown method which is executed at the end of every test.
     * the method deletes the current broker client.
     *
     * @author  mike@givingassistant.org
     * @version 1.0
     *
     *
     * HISTORY:
     * ========
     * 10-11-17     mks     CORE:584: original coding
     *
     */
    protected function tearDown()
    {
        /** @noinspection PhpUndefinedMethodInspection */
        $this->readBrokerClient->__destruct();
        unset($this->readBrokerClient);
    }


    /**
     * testTemplateReport() -- unit test method
     *
     * This method tests that we can (a) query the read-broker for a schema-fetch event and (b) that we receive
     * a template report.
     *
     * There's no detailed testing of the report contents as contents are fluid while the framework is in development.
     * However, this should be fleshed-out at a later date to test for fields specific to the PDO class in terms
     * of their existence as defined in the PDO test class: gatTestPDO.class.inc.
     *
     * @author  mike@givingassistant.org
     * @version 1.0
     *
     * HISTORY:
     * ========
     * 10-18-17     mks     CORE:584: original coding
     *
     */
    public function testTemplateReport()
    {
        // set up the broker event request
        $request = [
            BROKER_REQUEST => BROKER_REQUEST_SCHEMA,
            BROKER_DATA => null,
            BROKER_META_DATA => static::$meta
        ];

        // build the request payload and submit the request to the read broker
        $payload = gzcompress(json_encode($request));
        $response = $this->readBrokerClient->call($payload);
        $response = json_decode(gzuncompress($response), true);

        // validate: successful broker event
        $this->assertTrue(is_array($response), (__FILE__ . COLON . __LINE__) . COLON . ERROR_DATA_MISSING_ARRAY . 'response payload');
        // validate the status of the payload
        $this->assertTrue($response[PAYLOAD_STATUS], (__FILE__ . COLON . __LINE__) . COLON . ERROR_UT_EXPECTING_TRUE . 'not true');
    }

    /*
     * testRandomFetch() -- unit test method
     *
     * in this first test, we're going to submit a null query to the read broker, but we're going to constrain the
     * return data set by limiting the fetch to one record.  Since we're using the test-class, caching is enabled,
     * so we need to validate that a cache key was returned, and that the record was successfully cached in memory,
     * and that the cached object matches the object in the $data property and that the calculated checksum matches
     * the checksum value created when the object was cached.
     *
     * This is the simplest query we can submit to the broker.
     *
     *
     * @author  mike@givingassistant.org
     * @version 1.0
     *
     * HISTORY:
     * ========
     * 10-11-17     mks     CORE:584: original coding, ported for PDO from mongo
     * 01-17-19     mks     DB-105: support for audit/journal testing
     * 10-09-19     mks     DB-136: edge-case test for no test records in the db
     *
     */
    public function testRandomFetch()
    {
        $query = null;

        // limit the return data count to 1 record (we'll test for this...)

        $meta = static::$meta;
        $meta[META_LIMIT] = 1;
        static::$eventKey = guid();
        $this->assertTrue(validateGUID(static::$eventKey), basename(__FILE__) . COLON . __LINE__ . COLON . ERROR_INVALID_GUID . static::$eventKey);
        $meta[META_EVENT_GUID] = static::$eventKey;  // use a pre-generated guid for the query in the next method test

        // set up the broker request
        $request = [
            BROKER_REQUEST => BROKER_REQUEST_FETCH,
            BROKER_DATA => [STRING_QUERY_DATA => $query ],
            BROKER_META_DATA => $meta
        ];

        // build the request payload and submit the request to the read broker
        $payload = gzcompress(json_encode($request));
        $response = $this->readBrokerClient->call($payload);
        $response = json_decode(gzuncompress($response), true);

        // validate: successful broker event
        $this->assertTrue(is_array($response), (__FILE__ . COLON . __LINE__) . COLON . ERROR_DATA_MISSING_ARRAY . 'response payload');
        // validate the status of the payload
        $this->assertTrue($response[PAYLOAD_STATUS], (__FILE__ . COLON . __LINE__) . COLON . ERROR_UT_EXPECTING_TRUE . 'not true');
        // validate: return data has queryResults in payload
        $this->assertTrue(array_key_exists(STRING_QUERY_RESULTS, $response[PAYLOAD_RESULTS]), (__FILE__ . COLON . __LINE__) . COLON . ERROR_DATA_KEY_404 . STRING_QUERY_RESULTS);

        // if $response[results][queryResults] is null - there's no data in the db and doing this test is pointless
        if (is_null($response[PAYLOAD_RESULTS][STRING_QUERY_RESULTS])) {
            echo basename(__METHOD__) . AT . __LINE__ . COLON . PHP_EOL;
            echo 'Your table has no records to fetch - have you populated the table with test data?' . PHP_EOL;
            exit(1);
        }

        // validate one record was returned by counting the number of elements in the queryResults payload
        $this->assertEquals(1, count($response[PAYLOAD_RESULTS][STRING_QUERY_RESULTS]), (__FILE__ . COLON . __LINE__) . COLON . (sprintf(ERROR_DATA_RECORD_COUNT, 1, count($response[PAYLOAD_RESULTS][STRING_QUERY_RESULTS]))));
        // validate: return data has queryData in payload
        $this->assertTrue(array_key_exists(STRING_QUERY_DATA, $response[PAYLOAD_RESULTS]), (__FILE__ . COLON . __LINE__) . COLON . ERROR_DATA_KEY_404  . STRING_QUERY_DATA);
        // validate: we got the record returned count
        $this->assertTrue(array_key_exists(STRING_REC_COUNT_RET, $response[PAYLOAD_RESULTS][STRING_QUERY_DATA]), (__FILE__ . COLON . __LINE__) . COLON . ERROR_DATA_KEY_404 . STRING_REC_COUNT_RET);
        $recordsReturned = $response[PAYLOAD_RESULTS][STRING_QUERY_DATA][STRING_REC_COUNT_RET];
        // validate the recCount is an integer
        $this->assertTrue(is_int($recordsReturned), (__FILE__ . COLON . __LINE__) . COLON . ERROR_DATA_TYPE_MISMATCH . COLON . STRING_REC_COUNT_RET);
        // validate the recCount is = 1 because that's what we ordered with META_LIMIT
        $this->assertEquals(1, $recordsReturned, (__FILE__ . COLON . __LINE__) . COLON . ERROR_DATA_RANGE . COLON . STRING_REC_COUNT_RET);
        // validate that we got the total record count
        $this->assertTrue(array_key_exists(STRING_REC_COUNT_TOT, $response[PAYLOAD_RESULTS][STRING_QUERY_DATA]), (__FILE__ . COLON . __LINE__) . COLON . ERROR_DATA_KEY_404 . STRING_REC_COUNT_TOT);
        // validate that the total-rec-count is an integer
        static::$totalRecordCount = $response[PAYLOAD_RESULTS][STRING_QUERY_DATA][STRING_REC_COUNT_TOT];
        $this->assertTrue(is_int(static::$totalRecordCount), (__FILE__ . COLON . __LINE__) . COLON . ERROR_DATA_TYPE_MISMATCH . STRING_REC_COUNT_TOT);
        // validate that the total-rec count is > 0
        $this->assertGreaterThan(0, static::$totalRecordCount, (__FILE__ . COLON . __LINE__ ) . COLON . ERROR_DATA_RANGE . STRING_REC_COUNT_TOT);
        // extract the cacheKey
        $cacheKey = $response[PAYLOAD_RESULTS][STRING_QUERY_RESULTS][0];
        // validate that we can fetch data from cache using the key
        $record = gasCache::get($cacheKey);
        $this->assertNotFalse($record, (__FILE__ . COLON . __LINE__) . COLON . ERROR_UT_EXPECTING_TRUE . 'getCache::get(record)');
        $record = (array) json_decode(gzuncompress($record), true);
        // validate the checksum
        $cksum = $record[STRING_CHECKSUM];
        $rec = $record;
        unset($rec[STRING_CHECKSUM]);  // record is now back in it's original, pre-checksum, state
        $dataCheckSum = md5(gzcompress(json_encode($rec)));
        $this->assertEquals($cksum, $dataCheckSum, (__FILE__ . COLON . __LINE__) . COLON . ERROR_CACHE_DATA_CHECKSUM . $cacheKey);
        static::$dataKey = $record[0][STRING_KEY];
        // save the data key for the next test method
        $this->assertTrue(validateGUID(static::$dataKey), basename(__FILE__) . COLON . __LINE__ . COLON . ERROR_INVALID_GUID . static::$dataKey);
    }


    /**
     * testFetchAudit() -- unit test method
     *
     * This unit test verifies that the read event successfully created an audit record for the create event.  When
     * we query the admin database to fetch the audit record, the search is filtered by the record (data) guid and the
     * event guid that was manually created during the new-record-create event.
     *
     * The following assertions are made:
     *
     * 1-2: that data saved in previous methods is intact and available
     * 3: that the published broker event to fetch the audit record processed successfully
     * 4: that the audit record shows the event to be a record-accessed event
     *
     *
     * @author  mike@givingassistant.org
     * @version 1.0
     *
     *
     * HISTORY:
     * ========
     * 01-17-19     mks     DB-105: original coding
     *
     */
    public function testFetchAudit()
    {
        // pause for a second to allow the audit record to be written
        sleep(1);
        // test that we still have (saved) the two keys we need for this method's query
        $this->assertTrue(validateGUID(static::$eventKey), basename(__FILE__) . COLON . __LINE__ . COLON . ERROR_INVALID_GUID . static::$eventKey);
        $this->assertTrue(validateGUID(static::$dataKey), basename(__FILE__) . COLON . __LINE__ . COLON . ERROR_INVALID_GUID . static::$dataKey);

        // build a fetch event request to get the audit record
        $meta = static::$adminMeta;
        $meta[META_TEMPLATE] = TEMPLATE_CLASS_AUDIT;
        $query = [
            AUDIT_RECORD_TOKEN => [ OPERAND_NULL => [ OPERATOR_EQ => [ static::$dataKey ]]],
            DB_EVENT_GUID => [ OPERAND_NULL => [ OPERATOR_EQ => [ static::$eventKey ]]],
            OPERAND_AND => null
        ];
        $request = [
            BROKER_REQUEST => BROKER_REQUEST_REMOTE_FETCH,
            BROKER_DATA => [ STRING_QUERY_DATA => $query ],
            BROKER_META_DATA => $meta
        ];
        // submit the event request
        $response = json_decode(gzuncompress($this->adminOutClient->call(gzcompress(json_encode($request)))), true);
        $this->assertTrue($response[PAYLOAD_STATUS], basename(__FILE__) . COLON . __LINE__ . COLON . sprintf(ERROR_UT_BROKER_EVENT_FAIL, BROKER_REQUEST_REMOTE_FETCH, $response[PAYLOAD_STATE]));
        $operation = $response[PAYLOAD_RESULTS][PAYLOAD_QUERY][0][AUDIT_OPERATION . COLLECTION_MONGO_AUDIT_EXT];
        $this->assertEquals(EVENT_NAME_AUDIT_FETCH, $operation, (basename(__FILE__) . COLON . __LINE__) . COLON . sprintf(ERROR_UT_VALS_NOT_EQUAL, EVENT_NAME_AUDIT_FETCH, $operation));
    }


    /**
     * testNegativeFieldQuery() -- unit test method
     *
     * this unit test is a negative test - we want the framework to reject (fail) a request.  In this test, we're
     * going to submit a query that uses an invalid column name for the data class.  We'd expect the framework to
     * reject the request and we test for that rejection.
     *
     * @author mike@givingassistant.org
     * @version 1.0.
     *
     * HISTORY:
     * ========
     * 10-11-17     mks     CORE:584: original coding, ported for PDO from mongo test
     *
     */
    public function testNegativeFieldQuery()
    {
        $badField = 'fieldDoesNotExist';
        $query = [ $badField => [ OPERAND_NULL => [ OPERATOR_EQ => [1] ] ] ];
        $request = [
            BROKER_REQUEST => BROKER_REQUEST_FETCH,
            BROKER_DATA => [STRING_QUERY_DATA => $query ],
            BROKER_META_DATA => static::$meta
        ];
        // build the request payload and submit the request to the read broker
        $payload = gzcompress(json_encode($request));
        $response = $this->readBrokerClient->call($payload);
        $response = json_decode(gzuncompress($response), true);

        // validate that the return payload is an array
        $this->assertTrue(is_array($response), (__FILE__ . COLON . __LINE__) . COLON . ERROR_DATA_MISSING_ARRAY . 'broker response');
        // validate that the broker returned a false (success) response
        $this->assertFalse($response[PAYLOAD_STATUS], (__FILE__ . COLON . __LINE__) . COLON . ERROR_UT_EXPECTING_FALSE . PAYLOAD_STATUS);
        // validate that we returned a data error
        $this->assertEquals(STATE_DATA_ERROR, $response[PAYLOAD_STATE], (__FILE__ . COLON . __LINE__) . COLON . ERROR_INVALID_STATE . $response[PAYLOAD_STATE]);
        // validate the diagnostic message
        $expectedResponse = sprintf(ERROR_QB_ATTRIBUTE_404, $badField, (STRING_CLASS_GAT . TEMPLATE_CLASS_TEST_PDO));
        $gotResponse = $response[PAYLOAD_DIAGNOSTICS][0];
        $this->assertEquals($expectedResponse, $gotResponse, (__FILE__ . COLON . __LINE__) . COLON . sprintf(ERROR_UT_STRING_MISMATCH, $expectedResponse, $gotResponse));
    }


    /**
     * testNegativeNIFQuery() -- unit test method
     *
     * this is a negative unit test - we coded this to fail.  We want to submit a query with a predicate that
     * contains a non-indexed field (NIF).  One of the more-important features of Namaste is to evaluate and
     * qualify query requests.
     *
     * Namaste does not allow query predicates with non-indexed fields and should reject these requests with a
     * STATE_INDEX_ERROR state return.
     *
     *
     * @author  mike@givingassistant.org
     * @version 1.0
     *
     * HISTORY:
     * ========
     * 10-11-17     mks     CORE:584: original coding, ported for PDO from mongo test
     *
     */
    public function testNegativeNIFQuery()
    {
        // legit query -- all values are = 1, but the field is not indexed so query should be rejected
        $query = [ CM_TST_FIELD_TEST_NIF => [ OPERAND_NULL => [ OPERATOR_EQ => [ 42 ] ] ] ];
        $request = [
            BROKER_REQUEST => BROKER_REQUEST_FETCH,
            BROKER_DATA => [STRING_QUERY_DATA => $query ],
            BROKER_META_DATA => static::$meta
        ];
        // build the request payload and submit the request to the read broker
        $payload = gzcompress(json_encode($request));
        $response = $this->readBrokerClient->call($payload);
        $response = json_decode(gzuncompress($response), true);

        // validate the response payload
        $this->assertFalse($response[PAYLOAD_STATUS], (__FILE__ . COLON . __LINE__) . COLON . ERROR_UT_EXPECTING_FALSE . PAYLOAD_STATUS);
        $this->assertEquals(STATE_INDEX_ERROR , $response[PAYLOAD_STATE], (__FILE__ . COLON . __LINE__) . COLON . sprintf(ERROR_UT_FIELD_VALUE, PAYLOAD_STATE));
    }


    /**
     * testFetchAll() -- unit test method
     *
     * this test is going to launch a null-query test.  For this test to be successfully evaluated, you must have more
     * records in the database than the queryRecordLimit set in the XML configuration. (currently: 100)
     *
     * we're launching a "get all the records" query without a limit clause in an attempt at fetching all the records
     * in a collection.   This is a very bad thing if your collection has a hundred-million rows, or more, of data.
     *
     * the namaste xml file limits the number of records returned in any given fetch query.  When we submit a null
     * query, we're not including the limit-value in the meta payload -- this should tell the framework to fetch all
     * the collection's records.
     *
     * the framework should self-impose the record limit and that limit should be the value configured in the xml.
     * we're going to test for that value as the number of records returned.
     *
     *
     * @author  mike@givingassistant.org
     * @version 1.0
     *
     * HISTORY:
     * ========
     * 10-11-17     mks     CORE:584: original coding, ported for PDO from mongo test
     *
     */
    public function testFetchAll()
    {
        $recordLimit = gasConfig::$settings[CONFIG_DATABASE][CONFIG_DATABASE_QUERY_RECORD_LIMIT];

        if (isset(static::$meta[META_LIMIT])) unset(static::$meta[META_LIMIT]);
        if (isset(static::$meta[META_SKIP])) unset(static::$meta[META_SKIP]);

        $request = [
            BROKER_REQUEST => BROKER_REQUEST_FETCH,
            BROKER_DATA => [STRING_QUERY_DATA => null ],
            BROKER_META_DATA => static::$meta
        ];
        // build the request payload and submit the request to the read broker
        $payload = gzcompress(json_encode($request));
        $response = $this->readBrokerClient->call($payload);
        $response = json_decode(gzuncompress($response), true);

        // validate that the return payload is an array
        $this->assertTrue(is_array($response), (__FILE__ . COLON . __LINE__) . COLON . ERROR_DATA_MISSING_ARRAY . 'broker response');
        // validate that the payload returned was successful
        $this->assertTrue($response[PAYLOAD_STATUS], (__FILE__ . COLON . __LINE__) . COLON . ERROR_UT_EXPECTING_TRUE . PAYLOAD_STATUS);
        // validate that we returned the current-configured max-number of records
        $recsReturned = $response[PAYLOAD_RESULTS][STRING_QUERY_DATA][STRING_REC_COUNT_RET];
        $msg = sprintf(ERROR_UT_INTEGER_MISMATCH, $recordLimit, $recsReturned, STRING_REC_COUNT_RET);
        $this->assertLessThanOrEqual($recordLimit, $recsReturned, (__FILE__ . COLON . __LINE__) . COLON . $msg);
    }


    /**
     * testSkipLimit() -- unit test method
     *
     * this method validates the skip-limit processing accuracy for the framework.
     *
     * First, we're going to generate a random number that's equal to 25% of the total record count, +/- 10.
     * Next, exec a query that returns a list of 100 sorted guids, starting with the offset we just calculated
     * Next, generate a random number between 0 and 99 (1-100)
     * Next, save the sorted list of guids to an array
     * Next, exec a query that pulls that record (starting offset + rand-number) from the db
     * Last, compare the single returned value against the value in the list stored at the calculated offset
     *
     * I tried to limit the number of assertions in this test based on if the same assertions had been previously
     * tested in preceding methods.
     *
     *
     * @author mike@givingassistant.org
     * @version 1.0
     *
     * HISTORY:
     * ========
     * 10-11-17     mks     CORE:584: original coding, ported for PDO from mongo test
     * 10-17-17     mks     CORE:584: rewrote b/c we changed the payload on multiple returned records
     *
     */
    public function testSkipLimit()
    {
        $this->assertGreaterThan(0, static::$maxRecordCount, sprintf(ERROR_UT_FIELD_VALUE, 'maxRecordCount'));
        // build a query:  fetch all active records
        // point is to build a query that fetches a significant number of records...
        $query = [CM_TST_FIELD_TEST_STATUS => [ OPERAND_NULL => [ OPERATOR_EQ => [STATUS_ACTIVE]]]];

        // build the sort and projection arrays so we can test these options:
        $sort = [ CM_TST_TOKEN => STRING_SORT_ASC ];                                  // sort by data-created ascending
        $projection = [ CM_TST_TOKEN ];                                             // return a list of record guids

        // build the request
        $request = [
            BROKER_REQUEST => BROKER_REQUEST_FETCH,
            BROKER_DATA => [
                STRING_QUERY_DATA => $query,
                STRING_SORT_DATA => $sort,
                STRING_RETURN_DATA => $projection
            ],
            BROKER_META_DATA => static::$meta
        ];

        // launch the query and let's pull out the token list
        $payload = gzcompress(json_encode($request));
        $response = $this->readBrokerClient->call($payload);
        $response = json_decode(gzuncompress($response), true);

        // validate that the return payload is an array
        $this->assertTrue(is_array($response), (__FILE__ . COLON . __LINE__) . COLON . ERROR_DATA_MISSING_ARRAY . 'broker response');
        // validate that the payload returned was successful
        $this->assertTrue($response[PAYLOAD_STATUS], (__FILE__ . COLON . __LINE__) . COLON . ERROR_UT_EXPECTING_TRUE . PAYLOAD_STATUS);
        $this->assertNotEquals(STATE_NOT_FOUND, $response[PAYLOAD_STATE], basename(__METHOD__) . AT . __LINE__ . COLON . ERROR_UT_NOT_FOUND);
        // save a copy of the sorted record list - this because our validation authority
        $cacheGUID = $response[PAYLOAD_RESULTS][STRING_QUERY_RESULTS][0];
        $this->assertTrue(validateGUID(str_replace(gasConfig::$settings[CONFIG_ID][CONFIG_ID_ENV] . UDASH, '', $cacheGUID)), (__FILE__ . COLON . __LINE__) . ERROR_UT_CACHE_FETCH_FAIL);
        $recordList = json_decode(gzuncompress(gasCache::get($cacheGUID)), true);
        if (array_key_exists(STRING_CHECKSUM, $recordList)) unset($recordList[STRING_CHECKSUM]);
        $this->assertTrue(count($recordList) <= static::$maxRecordCount, (__FILE__ . COLON . __LINE__) . COLON . sprintf(ERROR_DATA_ARRAY_COUNT_EXCESSIVE, count($recordList), static::$maxRecordCount));
        // now - generate a new query to extract a random record within that range
        $recCount = count($recordList);
        $randomRecord = intval(mt_rand($recCount/4, $recCount));
        static::$meta[META_SKIP] = $randomRecord;
        static::$meta[META_LIMIT] = 1;      // and retrieve only that record

        // build the request
        $request = [
            BROKER_REQUEST => BROKER_REQUEST_FETCH,
            BROKER_DATA => [
                STRING_QUERY_DATA => $query,
                STRING_SORT_DATA => $sort,
                STRING_RETURN_DATA => $projection
            ],
            BROKER_META_DATA => static::$meta
        ];

        // submit the request and validate the payload return
        $payload = gzcompress(json_encode($request));
        $response = $this->readBrokerClient->call($payload);
        $response = json_decode(gzuncompress($response), true);

        // validate that the return payload is an array
        $this->assertTrue(is_array($response), (__FILE__ . COLON . __LINE__) . COLON . ERROR_DATA_MISSING_ARRAY . 'broker response');
        // validate that the payload returned was successful
        $this->assertTrue($response[PAYLOAD_STATUS], (__FILE__ . COLON . __LINE__) . COLON . ERROR_UT_EXPECTING_TRUE . PAYLOAD_STATUS);
        $newRecord = $response[PAYLOAD_RESULTS][STRING_QUERY_RESULTS][0];
        $newRecord = json_decode(gzuncompress(gasCache::get($newRecord)), true);
        $newRecordGuid = $newRecord[0][STRING_KEY];
        $oldRecGuid = $recordList[$randomRecord][STRING_KEY];
        $this->assertNotFalse(stristr($oldRecGuid, $newRecordGuid), (__FILE__ . COLON . __LINE__) . COLON . sprintf(ERROR_UT_VALS_NOT_EQUAL, $newRecordGuid, $oldRecGuid));
    }


    /**
     * testNonCachedFetch() -- public unit test method
     *
     * The purpose of this unit test is to publish a fetch event request using the META_DONUT_FILTER flag in the meta
     * data payload.  We're submitting the request and limiting the fetch to be a single record.
     *
     * We're injecting the META_DONUT_FILTER as part of the meta-data payload to force the request to return the
     * record containing the actual schema.
     *
     * The validation comes when we fetch the token from the record payload - each record is required to have one - and
     * the act of isolating that record involves querying by the class extension: implicit proof that we fetched
     * the pure version of the record.
     *
     *
     * @author  mike@givingassistant.org
     * @version 1.0
     *
     *
     * HISTORY:
     * ========
     * 05-23-19     mks     DB-40: unit-tests for non-cached data classes: original coding
     *
     */
    public function testNonCachedFetch()
    {
        $query = null;

        $metaCopy = static::$meta;
        // limit the return data count to 1 record (we'll test for this...)
        $metaCopy[META_LIMIT] = 1;
        $metaCopy[META_EVENT_GUID] = guid();
        $metaCopy[META_SYSTEM_NOTES] = basename(__METHOD__) . AT . __LINE__;
        $metaCopy[META_DONUT_FILTER] = 1;   // don't filter the return payload
        // set up the broker request
        $request = [
            BROKER_REQUEST => BROKER_REQUEST_FETCH,
            BROKER_DATA => [STRING_QUERY_DATA => $query ],
            BROKER_META_DATA => $metaCopy
        ];
        $payload = gzcompress(json_encode($request));
        $response = $this->readBrokerClient->call($payload);
        $response = json_decode(gzuncompress($response), true);
        // validate that the return payload is an array
        $this->assertTrue(is_array($response), (__FILE__ . COLON . __LINE__) . COLON . ERROR_DATA_MISSING_ARRAY . 'broker response');
        // validate that the payload returned was successful
        $this->assertTrue($response[PAYLOAD_STATUS], (__FILE__ . COLON . __LINE__) . COLON . ERROR_UT_EXPECTING_TRUE . PAYLOAD_STATUS);
        $tok = $response[PAYLOAD_RESULTS][STRING_QUERY_RESULTS][0][DB_TOKEN . TABLE_EXT_TEST];
        $this->assertTrue(validateGUID($tok), basename(__METHOD__) . AT . __LINE__ . COLON . ERROR_INVALID_GUID . $tok);
    }
}