Complete test migration

tests/Integration/ArrayDocument.php

@@ -0,0 +1,35 @@
+<?php
+/**
+ * @author Daniel J. Summers <daniel@bitbadger.solutions>
+ * @license MIT
+ */
+
+declare(strict_types=1);
+
+namespace Test\Integration;
+
+/**
+ * A document with an array of values
+ */
+class ArrayDocument
+{
+    /**
+     * @param string $id The ID of the document
+     * @param string[] $values The values for the document
+     */
+    public function __construct(public string $id = '', public array $values = []) { }
+
+    /**
+     * A set of documents used for integration tests
+     *
+     * @return ArrayDocument[] Test documents for InArray tests
+     */
+    public static function testDocuments(): array
+    {
+        return [
+            new ArrayDocument('first', ['a', 'b', 'c']),
+            new ArrayDocument('second', ['c', 'd', 'e']),
+            new ArrayDocument('third', ['x', 'y', 'z'])
+        ];
+    }
+}

tests/Integration/NumDocument.php

@@ -0,0 +1,17 @@
+<?php
+/**
+ * @author Daniel J. Summers <daniel@bitbadger.solutions>
+ * @license MIT
+ */
+
+declare(strict_types=1);
+
+namespace Test\Integration;
+
+/**
+ * A test document with a numeric ID
+ */
+class NumDocument
+{
+    public function __construct(public int $id = 0, public string $value = '') { }
+}

tests/Integration/SQLite/DocumentTest.php

@@ -6,23 +6,10 @@
 
 declare(strict_types=1);
 
-use BitBadger\PDODocument\{AutoId,
-    Configuration,
-    Count,
-    Custom,
-    Delete,
-    Document,
-    DocumentException,
-    DocumentList,
-    Exists,
-    Field,
-    Find,
-    Query};
-use BitBadger\PDODocument\Mapper\{ArrayMapper};
-use Test\Integration\NumDocument;
+use BitBadger\PDODocument\{AutoId, Configuration, Custom, Document, DocumentException, Exists, Field, Find};
+use BitBadger\PDODocument\Mapper\ArrayMapper;
+use Test\Integration\{NumDocument, SubDocument, TestDocument};
 use Test\Integration\SQLite\ThrowawayDb;
-use Test\Integration\SubDocument;
-use Test\Integration\TestDocument;
 
 pest()->group('integration', 'sqlite');
 

tests/Integration/SQLite/ExistsTest.php

@@ -0,0 +1,42 @@
+<?php
+/**
+ * @author Daniel J. Summers <daniel@bitbadger.solutions>
+ * @license MIT
+ */
+
+declare(strict_types=1);
+
+use BitBadger\PDODocument\{DocumentException, Exists, Field};
+use Test\Integration\SQLite\ThrowawayDb;
+
+pest()->group('integration', 'sqlite');
+
+describe('::byId()', function () {
+    test('returns true when a document exists', function () {
+        expect(Exists::byId(ThrowawayDb::TABLE, 'three'))->toBeTrue();
+    });
+    test('returns false when no document exists', function () {
+        expect(Exists::byId(ThrowawayDb::TABLE, 'seven'))->toBeFalse();
+    });
+});
+
+describe('::byFields()', function () {
+    test('returns true when matching documents exist', function () {
+        expect(Exists::byFields(ThrowawayDb::TABLE, [Field::equal('num_value', 10)]))->toBeTrue();
+    });
+    test('returns false when no matching documents exist', function () {
+        expect(Exists::byFields(ThrowawayDb::TABLE, [Field::less('nothing', 'none')]))->toBeFalse();
+    });
+});
+
+describe('::byContains()', function () {
+    test('throws an exception', function () {
+        expect(fn () => Exists::byContains('', []))->toThrow(DocumentException::class);
+    });
+});
+
+describe('::byJsonPath()', function () {
+    test('throws an exception', function () {
+        expect(fn () => Exists::byJsonPath('', ''))->toThrow(DocumentException::class);
+    });
+});

tests/Integration/SQLite/FindTest.php

@@ -0,0 +1,151 @@
+<?php
+/**
+ * @author Daniel J. Summers <daniel@bitbadger.solutions>
+ * @license MIT
+ */
+
+declare(strict_types=1);
+
+use BitBadger\PDODocument\{Custom, Delete, Document, DocumentException, Field, FieldMatch, Find};
+use Test\Integration\{ArrayDocument, TestDocument};
+use Test\Integration\SQLite\ThrowawayDb;
+
+pest()->group('integration', 'sqlite');
+
+describe('::all()', function () {
+    test('retrieves data', function () {
+        $docs = Find::all(ThrowawayDb::TABLE, TestDocument::class);
+        expect($docs)->not->toBeNull();
+        $count = 0;
+        foreach ($docs->items() as $ignored) $count++;
+        expect($count)->toBe(5);
+    });
+    test('sorts data ascending', function () {
+        $docs = Find::all(ThrowawayDb::TABLE, TestDocument::class, [Field::named('id')]);
+        expect($docs)->not->toBeNull()
+            ->and(iterator_to_array($docs->map(fn ($it) => $it->id), false))
+            ->toBe(['five', 'four', 'one', 'three', 'two']);
+    });
+    test('sorts data descending', function () {
+        $docs = Find::all(ThrowawayDb::TABLE, TestDocument::class, [Field::named('id DESC')]);
+        expect($docs)->not->toBeNull()
+            ->and(iterator_to_array($docs->map(fn ($it) => $it->id), false))
+            ->toBe(['two', 'three', 'one', 'four', 'five']);
+    });
+    test('sorts data numerically', function () {
+        $docs = Find::all(ThrowawayDb::TABLE, TestDocument::class,
+            [Field::named('sub.foo NULLS LAST'), Field::named('n:num_value')]);
+        expect($docs)->not->toBeNull()
+            ->and(iterator_to_array($docs->map(fn ($it) => $it->id), false))
+            ->toBe(['two', 'four', 'one', 'three', 'five']);
+    });
+    test('returns an empty list when no data exists', function () {
+        Custom::nonQuery('DELETE FROM ' . ThrowawayDb::TABLE, []);
+        expect(Find::all(ThrowawayDb::TABLE, TestDocument::class))
+            ->not->toBeNull()->hasItems()->toBeFalse();
+    });
+});
+
+describe('::byId()', function () {
+    test('returns a document when it exists', function () {
+        expect(Find::byId(ThrowawayDb::TABLE, 'two', TestDocument::class))
+            ->isSome()->toBeTrue()->get()->id->toBe('two');
+    });
+    test('returns a document with a numeric ID', function () {
+        Document::insert(ThrowawayDb::TABLE, ['id' => 18, 'value' => 'howdy']);
+        expect(Find::byId(ThrowawayDb::TABLE, 18, TestDocument::class))
+            ->isSome()->toBeTrue()->get()->id->toBe('18');
+    });
+    test('returns None when no document exists', function () {
+        expect(Find::byId(ThrowawayDb::TABLE, 'seventy-five', TestDocument::class))->isNone()->toBeTrue();
+    });
+});
+
+describe('::byFields()', function () {
+    test('returns matching documents', function () {
+        $docs = Find::byFields(ThrowawayDb::TABLE, [Field::in('value', ['blue', 'purple']), Field::exists('sub')],
+            TestDocument::class, FieldMatch::All);
+        expect($docs)->not->toBeNull();
+        $count = 0;
+        foreach ($docs->items() as $ignored) $count++;
+        expect($count)->toBe(1);
+    });
+    test('returns ordered matching documents', function () {
+        $docs = Find::byFields(ThrowawayDb::TABLE, [Field::equal('value', 'purple')], TestDocument::class,
+            FieldMatch::All, [Field::named('id')]);
+        expect($docs)->not->toBeNull()
+            ->and(iterator_to_array($docs->map(fn ($it) => $it->id), false))->toBe(['five', 'four']);
+    });
+    test('returns documents matching numeric IN clause', function () {
+        $docs = Find::byFields(ThrowawayDb::TABLE, [Field::in('num_value', [2, 4, 6, 8])], TestDocument::class);
+        expect($docs)->not->toBeNull();
+        $count = 0;
+        foreach ($docs->items() as $ignored) $count++;
+        expect($count)->toBe(1);
+    });
+    test('returns empty list when no documents match', function () {
+        expect(Find::byFields(ThrowawayDb::TABLE, [Field::greater('num_value', 100)], TestDocument::class))
+            ->not->toBeNull()->hasItems()->toBeFalse();
+    });
+    test('returns matching documents for inArray comparison', function () {
+        Delete::byFields(ThrowawayDb::TABLE, [Field::notExists('absentField')]);
+        foreach (ArrayDocument::testDocuments() as $doc) Document::insert(ThrowawayDb::TABLE, $doc);
+        $docs = Find::byFields(ThrowawayDb::TABLE, [Field::inArray('values', ThrowawayDb::TABLE, ['c'])],
+            ArrayDocument::class);
+        expect($docs)->not->toBeNull();
+        $count = 0;
+        foreach ($docs->items() as $ignored) $count++;
+        expect($count)->toBe(2);
+    });
+    test('returns empty list when no documents match inArray comparison', function () {
+        Delete::byFields(ThrowawayDb::TABLE, [Field::notExists('absentField')]);
+        foreach (ArrayDocument::testDocuments() as $doc) Document::insert(ThrowawayDb::TABLE, $doc);
+        expect(Find::byFields(ThrowawayDb::TABLE, [Field::inArray('values', ThrowawayDb::TABLE, ['j'])],
+                ArrayDocument::class))
+            ->not->toBeNull()->hasItems()->toBeFalse();
+    });
+});
+
+describe('::byContains()', function () {
+    test('throws an exception', function () {
+        expect(fn () => Find::byContains('', [], TestDocument::class))->toThrow(DocumentException::class);
+    });
+});
+
+describe('::byJsonPath()', function () {
+    test('throws an exception', function () {
+        expect(fn () => Find::byJsonPath('', '', TestDocument::class))->toThrow(DocumentException::class);
+    });
+});
+
+describe('::firstByFields()', function () {
+    test('returns a matching document', function () {
+        expect(Find::firstByFields(ThrowawayDb::TABLE, [Field::equal('value', 'another')], TestDocument::class))
+            ->isSome()->toBeTrue()->get()->id->toBe('two');
+    });
+    test('returns one of several matching documents', function () {
+        $doc = Find::firstByFields(ThrowawayDb::TABLE, [Field::equal('sub.foo', 'green')], TestDocument::class);
+        expect($doc)->isSome()->toBeTrue()->and(['two', 'four'])->toContain($doc->get()->id);
+    });
+    test('returns first of ordered matching documents', function () {
+        expect(Find::firstByFields(ThrowawayDb::TABLE, [Field::equal('sub.foo', 'green')], TestDocument::class,
+                orderBy: [Field::named('n:num_value DESC')]))
+            ->isSome()->toBeTrue()->get()->id->toBe('four');
+    });
+    test('returns None when no documents match', function () {
+        expect(Find::firstByFields(ThrowawayDb::TABLE, [Field::equal('value', 'absent')], TestDocument::class))
+            ->isNone()->toBeTrue();
+    });
+});
+
+describe('::firstByContains()', function () {
+    test('throws an exception', function () {
+        expect(fn () => Find::firstByContains('', [], TestDocument::class))->toThrow(DocumentException::class);
+    });
+});
+
+describe('::firstByJsonPath()', function () {
+    test('throws an exception', function () {
+        expect(fn () => Find::firstByJsonPath('', '', TestDocument::class))->toThrow(DocumentException::class);
+    });
+});

tests/Integration/SQLite/PatchTest.php

@@ -0,0 +1,48 @@
+<?php
+/**
+ * @author Daniel J. Summers <daniel@bitbadger.solutions>
+ * @license MIT
+ */
+
+declare(strict_types=1);
+
+use BitBadger\PDODocument\{Count, DocumentException, Exists, Field, Find, Patch};
+use Test\Integration\SQLite\ThrowawayDb;
+use Test\Integration\TestDocument;
+
+pest()->group('integration', 'sqlite');
+
+describe('::byId()', function () {
+    test('updates an existing document', function () {
+        Patch::byId(ThrowawayDb::TABLE, 'one', ['num_value' => 44]);
+        expect(Find::byId(ThrowawayDb::TABLE, 'one', TestDocument::class))
+            ->isSome()->toBeTrue()->get()->num_value->toBe(44);
+    });
+    test('does nothing when no document exists', function () {
+        expect(Exists::byId(ThrowawayDb::TABLE, 'forty-seven'))->toBeFalse();
+        Patch::byId(ThrowawayDb::TABLE, 'forty-seven', ['foo' => 'green']);
+    });
+});
+
+describe('::byFields()', function () {
+    test('updates matching documents', function () {
+        Patch::byFields(ThrowawayDb::TABLE, [Field::equal('value', 'purple')], ['num_value' => 77]);
+        expect(Count::byFields(ThrowawayDb::TABLE, [Field::equal('num_value', 77)]))->toBe(2);
+    });
+    test('does nothing when no documents match', function () {
+        expect(Exists::byFields(ThrowawayDb::TABLE, [Field::equal('value', 'burgundy')]))->toBeFalse();
+        Patch::byFields(ThrowawayDb::TABLE, [Field::equal('value', 'burgundy')], ['foo' => 'green']);
+    });
+});
+
+describe('::byContains()', function () {
+    test('throws an exception', function () {
+        expect(fn () => Patch::byContains('', [], []))->toThrow(DocumentException::class);
+    });
+});
+
+describe('::byJsonPath()', function () {
+    test('throws an exception', function () {
+        expect(fn () => Patch::byJsonPath('', '', []))->toThrow(DocumentException::class);
+    });
+});

tests/Integration/SQLite/RemoveFieldsTest.php

@@ -0,0 +1,59 @@
+<?php
+/**
+ * @author Daniel J. Summers <daniel@bitbadger.solutions>
+ * @license MIT
+ */
+
+declare(strict_types=1);
+
+use BitBadger\PDODocument\{DocumentException, Exists, Field, Find, RemoveFields};
+use Test\Integration\SQLite\ThrowawayDb;
+use Test\Integration\TestDocument;
+
+pest()->group('integration', 'sqlite');
+
+describe('::byId()', function () {
+    test('updates an existing document', function () {
+        RemoveFields::byId(ThrowawayDb::TABLE, 'two', ['sub', 'value']);
+        $tryDoc = Find::byId(ThrowawayDb::TABLE, 'two', TestDocument::class);
+        expect($tryDoc)->isSome()->toBeTrue()
+            ->and($tryDoc->get())->sub->toBeNull()
+            ->and($tryDoc->get()->value)->toBeEmpty();
+    });
+    test('does nothing when the field to remove does not exist', function () {
+        expect(Exists::byFields(ThrowawayDb::TABLE, [Field::exists('a_field_that_does_not_exist')]))->toBeFalse();
+        RemoveFields::byId(ThrowawayDb::TABLE, 'one', ['a_field_that_does_not_exist']);
+    });
+    test('does nothing when the document does not exist', function () {
+        expect(Exists::byId(ThrowawayDb::TABLE, 'fifty'))->toBeFalse();
+        RemoveFields::byId(ThrowawayDb::TABLE, 'fifty', ['sub']);
+    });
+});
+
+describe('::byFields()', function () {
+    test('updates matching documents', function () {
+        RemoveFields::byFields(ThrowawayDb::TABLE, [Field::equal('num_value', 17)], ['sub']);
+        expect(Find::firstByFields(ThrowawayDb::TABLE, [Field::equal('num_value', 17)], TestDocument::class))
+            ->isSome()->toBeTrue()->get()->sub->toBeNull();
+    });
+    test('does nothing when the field to remove does not exist', function () {
+        expect(Exists::byFields(ThrowawayDb::TABLE, [Field::exists('nada')]))->toBeFalse();
+        RemoveFields::byFields(ThrowawayDb::TABLE, [Field::equal('num_value', 17)], ['nada']);
+    });
+    test('does nothing when no documents match', function () {
+        expect(Exists::byFields(ThrowawayDb::TABLE, [Field::notEqual('missing', 'nope')]))->toBeFalse();
+        RemoveFields::byFields(ThrowawayDb::TABLE, [Field::notEqual('missing', 'nope')], ['value']);
+    });
+});
+
+describe('::byContains()', function () {
+    test('throws an exception', function () {
+        expect(fn () => RemoveFields::byContains('', [], []))->toThrow(DocumentException::class);
+    });
+});
+
+describe('::byJsonPath()', function () {
+    test('throws an exception', function () {
+        expect(fn () => RemoveFields::byJsonPath('', '', []))->toThrow(DocumentException::class);
+    });
+});

tests/Integration/SQLite/ThrowawayDb.php

@@ -0,0 +1,70 @@
+<?php
+/**
+ * @author Daniel J. Summers <daniel@bitbadger.solutions>
+ * @license MIT
+ * @see https://github.com/Zaid-Ajaj/ThrowawayDb The origin concept
+ */
+
+declare(strict_types=1);
+
+namespace Test\Integration\SQLite;
+
+use BitBadger\PDODocument\{AutoId, Configuration, Definition, Document, DocumentException};
+use Random\RandomException;
+use Test\Integration\{SubDocument, TestDocument};
+
+/**
+ * Utilities to create and destroy a throwaway SQLite database to use for testing
+ */
+class ThrowawayDb
+{
+    /** @var string The table used for document manipulation */
+    public const TABLE = 'test_table';
+
+    /**
+     * Load data into the test table
+     *
+     * @throws DocumentException If any is encountered
+     */
+    public static function loadData(): void
+    {
+        Document::insert(self::TABLE, new TestDocument('one', 'FIRST!', 0));
+        Document::insert(self::TABLE, new TestDocument('two', 'another', 10, new SubDocument('green', 'blue')));
+        Document::insert(self::TABLE, new TestDocument('three', '', 4));
+        Document::insert(self::TABLE, new TestDocument('four', 'purple', 17, new SubDocument('green', 'red')));
+        Document::insert(self::TABLE, new TestDocument('five', 'purple', 18));
+    }
+
+    /**
+     * Create a throwaway SQLite database
+     *
+     * @param bool $withData Whether to initialize this database with data (optional; defaults to `true`)
+     * @return string The name of the database (use to pass to `destroy` function at end of test)
+     * @throws DocumentException|RandomException If any is encountered
+     */
+    public static function create(bool $withData = true): string
+    {
+        $fileName = sprintf('throwaway-%s.db', AutoId::generateRandom(10));
+        Configuration::useDSN("sqlite:./$fileName");
+        Configuration::resetPDO();
+
+        Definition::ensureTable(self::TABLE);
+
+        if ($withData) {
+            self::loadData();
+        }
+
+        return $fileName;
+    }
+
+    /**
+     * Destroy a throwaway SQLite database
+     *
+     * @param string $fileName The name of the SQLite database to be deleted
+     */
+    public static function destroy(string $fileName): void
+    {
+        Configuration::resetPDO();
+        if (file_exists("./$fileName")) unlink("./$fileName");
+    }
+}

tests/Integration/SubDocument.php

@@ -0,0 +1,17 @@
+<?php
+/**
+ * @author Daniel J. Summers <daniel@bitbadger.solutions>
+ * @license MIT
+ */
+
+declare(strict_types=1);
+
+namespace Test\Integration;
+
+/**
+ * A sub-document for testing
+ */
+class SubDocument
+{
+    public function __construct(public string $foo = '', public string $bar = '') { }
+}

tests/Integration/TestDocument.php

@@ -0,0 +1,15 @@
+<?php
+/**
+ * @author Daniel J. Summers <daniel@bitbadger.solutions>
+ * @license MIT
+ */
+
+declare(strict_types=1);
+
+namespace Test\Integration;
+
+class TestDocument
+{
+    public function __construct(public string $id = '', public string $value = '', public int $num_value = 0,
+                                public ?SubDocument $sub = null) { }
+}