Skip to content

A free open source IT asset/license management system

Add failing tests for acceptance quantity for accessories when checking in

Marcus Moore22eaaa7c9f14
diff --git a/tests/Feature/CheckoutAcceptances/PendingAcceptanceQuantityOnCheckinTest.php b/tests/Feature/CheckoutAcceptances/PendingAcceptanceQuantityOnCheckinTest.php
new file mode 100644
index 0000000000..b6edb2d827
--- /dev/null
+++ b/tests/Feature/CheckoutAcceptances/PendingAcceptanceQuantityOnCheckinTest.php
@@ -0,0 +1,516 @@
+<?php
+
+namespace Tests\Feature\CheckoutAcceptances;
+
+use App\Models\Accessory;
+use App\Models\Asset;
+use App\Models\AssetModel;
+use App\Models\Category;
+use App\Models\CheckoutAcceptance;
+use App\Models\License;
+use App\Models\LicenseSeat;
+use App\Models\User;
+use Illuminate\Support\Facades\Mail;
+use PHPUnit\Framework\Attributes\Test;
+use Tests\TestCase;
+
+/**
+ * After checking an item in, the holder should be left owing an acceptance for
+ * exactly the units they still hold and have not already accepted. No more, or
+ * they are prompted to accept units they gave back. No fewer, or a unit they
+ * still hold has no acceptance record and they are never prompted at all.
+ *
+ * Written as an assertion, that is:
+ *
+ * SUM(pending qty) == max(0, units held - units accepted)
+ *
+ * The subtraction only matters once something has been accepted, so most tests
+ * below are really just "pending qty == units held".
+ *
+ * Why this is not trivially true: two tables look 1:1 and are not.
+ * accessories_checkout holds one row per UNIT, while checkout_acceptances holds
+ * one row per CHECKOUT ACTION carrying its qty — so checking out 3 gives three
+ * pivot rows but a single acceptance row. Checking one unit back in therefore
+ * has to retire one unit, not a row that may be worth three.
+ *
+ * Accessory units are fungible — no serial, no tag — so there is no fact about
+ * WHICH unit came back. A checkin is therefore DEFINED to retire an unaccepted
+ * unit, oldest acceptance first, which is what makes the assertion above
+ * well-defined at all.
+ *
+ * Acceptance is all-or-nothing per row, so a qty-3 row cannot be partially
+ * accepted and mixed accepted/unaccepted states only arise from separate
+ * checkouts.
+ */
+class PendingAcceptanceQuantityOnCheckinTest extends TestCase
+{
+ protected function setUp(): void
+ {
+ parent::setUp();
+
+ Mail::fake();
+ $this->settings->disableAdminCC()->disableAdminCCAlways()->disableSlackWebhook();
+ }
+
+ // ─────────────────────────────────────────────────────────────────────
+ // ACCESSORIES — the only checkin-able quantity type
+ // ─────────────────────────────────────────────────────────────────────
+
+ #[Test]
+ public function checking_in_the_only_unit_clears_the_acceptance(): void
+ {
+ [$accessory, $user] = $this->accessoryAndUser();
+ $this->checkOut($accessory, $user, qty: 1);
+
+ $this->checkIn($this->oneHeldCheckoutOf($accessory, $user));
+
+ $this->assertPendingQtyMatchesUnacceptedUnitsHeld($accessory, $user);
+ }
+
+ #[Test]
+ public function checking_in_one_of_two_single_unit_checkouts_leaves_the_other_outstanding(): void
+ {
+ [$accessory, $user] = $this->accessoryAndUser();
+ $this->checkOut($accessory, $user, qty: 1);
+ $this->checkOut($accessory, $user, qty: 1);
+
+ $this->checkIn($this->oneHeldCheckoutOf($accessory, $user));
+
+ $this->assertPendingQtyMatchesUnacceptedUnitsHeld($accessory, $user);
+ }
+
+ #[Test]
+ public function checking_in_one_unit_of_a_two_unit_checkout_decrements_that_acceptance(): void
+ {
+ [$accessory, $user] = $this->accessoryAndUser();
+ $this->checkOut($accessory, $user, qty: 2);
+
+ // One row worth 2 units: no delete-a-row strategy can be right here.
+ $this->assertSame(1, $this->pendingRowCount($accessory, $user));
+
+ $this->checkIn($this->oneHeldCheckoutOf($accessory, $user));
+
+ $this->assertPendingQtyMatchesUnacceptedUnitsHeld($accessory, $user);
+ }
+
+ #[Test]
+ public function checking_in_one_unit_across_two_checkouts_of_different_sizes(): void
+ {
+ [$accessory, $user] = $this->accessoryAndUser();
+ $this->checkOut($accessory, $user, qty: 2);
+ $this->checkOut($accessory, $user, qty: 1);
+
+ $this->checkIn($this->oneHeldCheckoutOf($accessory, $user));
+
+ $this->assertPendingQtyMatchesUnacceptedUnitsHeld($accessory, $user);
+ }
+
+ #[Test]
+ public function checking_in_every_unit_of_a_multi_unit_checkout_clears_the_acceptance(): void
+ {
+ [$accessory, $user] = $this->accessoryAndUser();
+ $this->checkOut($accessory, $user, qty: 2);
+
+ $this->checkIn($this->oneHeldCheckoutOf($accessory, $user));
+ $this->checkIn($this->oneHeldCheckoutOf($accessory, $user));
+
+ $this->assertPendingQtyMatchesUnacceptedUnitsHeld($accessory, $user);
+ }
+
+ #[Test]
+ public function retiring_more_units_than_the_oldest_acceptance_holds_spills_into_the_next(): void
+ {
+ [$accessory, $user] = $this->accessoryAndUser();
+ $this->checkOut($accessory, $user, qty: 3);
+ $this->checkOut($accessory, $user, qty: 2);
+
+ // Retiring four of five units has to exhaust the first row and bite
+ // into the second, which "one row per checkin" cannot do.
+ for ($i = 0; $i < 4; $i++) {
+ $this->checkIn($this->oneHeldCheckoutOf($accessory, $user));
+ }
+
+ $this->assertSame(1, $this->unitsHeld($accessory, $user));
+ $this->assertPendingQtyMatchesUnacceptedUnitsHeld($accessory, $user);
+ }
+
+ // ─────────────────────────────────────────────────────────────────────
+ // MIXED accepted / pending — accepted rows are history and stay untouched
+ // ─────────────────────────────────────────────────────────────────────
+
+ #[Test]
+ public function checking_in_when_one_of_three_single_unit_checkouts_is_already_accepted(): void
+ {
+ [$accessory, $user] = $this->accessoryAndUser();
+ $this->checkOut($accessory, $user, qty: 1);
+ $this->checkOut($accessory, $user, qty: 1);
+ $this->checkOut($accessory, $user, qty: 1);
+
+ $accepted = $this->acceptPendingRow($accessory, $user, index: 1);
+
+ $this->checkIn($this->oneHeldCheckoutOf($accessory, $user));
+
+ $this->assertSame(2, $this->unitsHeld($accessory, $user));
+ $this->assertPendingQtyMatchesUnacceptedUnitsHeld($accessory, $user);
+ $this->assertAcceptedRowUntouched($accepted, expectedQty: 1);
+ }
+
+ #[Test]
+ public function checking_in_when_a_middle_sized_checkout_is_already_accepted(): void
+ {
+ [$accessory, $user] = $this->accessoryAndUser();
+ $this->checkOut($accessory, $user, qty: 2);
+ $this->checkOut($accessory, $user, qty: 1);
+ $this->checkOut($accessory, $user, qty: 3);
+
+ // Rows of differing size, so nothing passes by conflating rows/units.
+ $this->assertSame(6, $this->unitsHeld($accessory, $user));
+
+ $accepted = $this->acceptPendingRow($accessory, $user, index: 1);
+
+ $this->checkIn($this->oneHeldCheckoutOf($accessory, $user));
+
+ $this->assertSame(5, $this->unitsHeld($accessory, $user));
+ $this->assertPendingQtyMatchesUnacceptedUnitsHeld($accessory, $user);
+ $this->assertAcceptedRowUntouched($accepted, expectedQty: 1);
+ }
+
+ #[Test]
+ public function checking_in_two_units_when_the_largest_checkout_is_already_accepted(): void
+ {
+ [$accessory, $user] = $this->accessoryAndUser();
+ $this->checkOut($accessory, $user, qty: 2);
+ $this->checkOut($accessory, $user, qty: 1);
+ $this->checkOut($accessory, $user, qty: 3);
+
+ $accepted = $this->acceptPendingRow($accessory, $user, index: 2);
+
+ $this->checkIn($this->oneHeldCheckoutOf($accessory, $user));
+ $this->checkIn($this->oneHeldCheckoutOf($accessory, $user));
+
+ $this->assertSame(4, $this->unitsHeld($accessory, $user));
+ $this->assertPendingQtyMatchesUnacceptedUnitsHeld($accessory, $user);
+ $this->assertAcceptedRowUntouched($accepted, expectedQty: 3);
+ }
+
+ #[Test]
+ public function checking_in_against_a_fully_accepted_checkout_leaves_nothing_to_retire(): void
+ {
+ [$accessory, $user] = $this->accessoryAndUser();
+ $this->checkOut($accessory, $user, qty: 3);
+
+ $accepted = $this->acceptPendingRow($accessory, $user, index: 0);
+ $this->assertSame(0, $this->pendingQtySum($accessory, $user), 'Accepting the only row should leave nothing pending.');
+
+ $this->checkIn($this->oneHeldCheckoutOf($accessory, $user));
+
+ // Nothing outstanding, so nothing to retire. The accepted row must not
+ // be decremented to balance the books.
+ $this->assertSame(2, $this->unitsHeld($accessory, $user));
+ $this->assertPendingQtyMatchesUnacceptedUnitsHeld($accessory, $user);
+ $this->assertAcceptedRowUntouched($accepted, expectedQty: 3);
+ }
+
+ #[Test]
+ public function an_accepted_acceptance_is_not_consumed_while_an_unaccepted_unit_remains(): void
+ {
+ [$accessory, $user] = $this->accessoryAndUser();
+ $this->checkOut($accessory, $user, qty: 2);
+ $this->checkOut($accessory, $user, qty: 1);
+
+ $accepted = $this->acceptPendingRow($accessory, $user, index: 0);
+ $this->assertSame(1, $this->pendingQtySum($accessory, $user));
+
+ $this->checkIn($this->oneHeldCheckoutOf($accessory, $user));
+
+ $this->assertSame(2, $this->unitsHeld($accessory, $user));
+ $this->assertPendingQtyMatchesUnacceptedUnitsHeld($accessory, $user);
+ $this->assertAcceptedRowUntouched($accepted, expectedQty: 2);
+ }
+
+ // ─────────────────────────────────────────────────────────────────────
+ // ACCESSORIES via the user-item transfer feature
+ // ─────────────────────────────────────────────────────────────────────
+
+ #[Test]
+ public function transferring_one_of_two_single_unit_checkouts_leaves_the_other_outstanding(): void
+ {
+ [$accessory, $source] = $this->accessoryAndUser();
+ $target = User::factory()->create();
+
+ $this->checkOut($accessory, $source, qty: 1);
+ $this->checkOut($accessory, $source, qty: 1);
+
+ $this->transfer($source, $target, $this->oneHeldCheckoutOf($accessory, $source));
+
+ $this->assertPendingQtyMatchesUnacceptedUnitsHeld($accessory, $source);
+ }
+
+ #[Test]
+ public function transferring_one_unit_of_a_two_unit_checkout_decrements_that_acceptance(): void
+ {
+ [$accessory, $source] = $this->accessoryAndUser();
+ $target = User::factory()->create();
+
+ $this->checkOut($accessory, $source, qty: 2);
+
+ $this->transfer($source, $target, $this->oneHeldCheckoutOf($accessory, $source));
+
+ $this->assertPendingQtyMatchesUnacceptedUnitsHeld($accessory, $source);
+ }
+
+ #[Test]
+ public function transferring_retires_exactly_one_unit_not_two(): void
+ {
+ [$accessory, $source] = $this->accessoryAndUser();
+ $target = User::factory()->create();
+
+ $this->checkOut($accessory, $source, qty: 3);
+
+ // Transfer used to clear pendings inline AND fire the checkin event, so
+ // both paths retired a unit. Holding three exposes it: over-retire
+ // lands on 1, not 2.
+ $this->transfer($source, $target, $this->oneHeldCheckoutOf($accessory, $source));
+
+ $this->assertSame(2, $this->unitsHeld($accessory, $source));
+ $this->assertSame(2, $this->pendingQtySum($accessory, $source), 'A single transfer must retire exactly one unit of pending qty.');
+ }
+
+ // ─────────────────────────────────────────────────────────────────────
+ // CONTROLS — 1:1 types. These should already be correct.
+ // ─────────────────────────────────────────────────────────────────────
+
+ #[Test]
+ public function checking_in_one_license_seat_leaves_the_other_seats_acceptance_alone(): void
+ {
+ $user = User::factory()->create();
+ $license = License::factory()->create([
+ 'reassignable' => 1,
+ 'seats' => 5,
+ 'category_id' => Category::factory()->forLicenses()->requiresAcceptance()->doesNotSendCheckinEmail(),
+ ]);
+
+ $seatA = $this->checkOutSeat($license, $user);
+ $seatB = $this->checkOutSeat($license, $user);
+
+ $this->actingAs(User::factory()->superuser()->create())
+ ->post(route('licenses.checkin.save', $seatA->id))
+ ->assertRedirect();
+
+ $this->assertSame(0, $this->pendingRowCountFor(LicenseSeat::class, $seatA->id, $user),
+ 'Checked-in seat should have no pending acceptance left.');
+ $this->assertSame(1, $this->pendingRowCountFor(LicenseSeat::class, $seatB->id, $user),
+ 'The seat the user still holds must keep its pending acceptance.');
+ }
+
+ #[Test]
+ public function checking_in_an_asset_clears_its_single_acceptance(): void
+ {
+ $user = User::factory()->create();
+ $asset = Asset::factory()->assignedToUser($user)->create([
+ 'model_id' => AssetModel::factory()->create([
+ 'category_id' => Category::factory()->forAssets()->requiresAcceptance()->doesNotSendCheckinEmail(),
+ ]),
+ ]);
+
+ CheckoutAcceptance::factory()->withoutActionLog()->pending()->create([
+ 'checkoutable_type' => Asset::class,
+ 'checkoutable_id' => $asset->id,
+ 'assigned_to_id' => $user->id,
+ 'qty' => 1,
+ ]);
+
+ $this->actingAs(User::factory()->superuser()->create())
+ ->post(route('hardware.checkin.store', $asset->id))
+ ->assertRedirect();
+
+ $this->assertSame(0, $this->pendingRowCountFor(Asset::class, $asset->id, $user),
+ 'Asset checkin should clear its single pending acceptance.');
+ }
+
+ #[Test]
+ public function checking_in_an_asset_whose_acceptance_has_a_null_qty_still_clears_it(): void
+ {
+ $user = User::factory()->create();
+ $asset = Asset::factory()->assignedToUser($user)->create([
+ 'model_id' => AssetModel::factory()->create([
+ 'category_id' => Category::factory()->forAssets()->requiresAcceptance()->doesNotSendCheckinEmail(),
+ ]),
+ ]);
+
+ // AssetCheckoutController never passes a qty, so every real asset
+ // acceptance is null. Null must read as one unit or 1:1 stops clearing.
+ $acceptance = CheckoutAcceptance::factory()->withoutActionLog()->pending()->create([
+ 'checkoutable_type' => Asset::class,
+ 'checkoutable_id' => $asset->id,
+ 'assigned_to_id' => $user->id,
+ 'qty' => null,
+ ]);
+ $this->assertNull($acceptance->qty);
+
+ $this->actingAs(User::factory()->superuser()->create())
+ ->post(route('hardware.checkin.store', $asset->id))
+ ->assertRedirect();
+
+ $this->assertSame(0, $this->pendingRowCountFor(Asset::class, $asset->id, $user));
+ }
+
+ // ─────────────────────────────────────────────────────────────────────
+ // Helpers
+ // ─────────────────────────────────────────────────────────────────────
+
+ /** @return array{0: Accessory, 1: User} */
+ private function accessoryAndUser(): array
+ {
+ $accessory = Accessory::factory()->create([
+ 'category_id' => Category::factory()->forAccessories()->requiresAcceptance()->doesNotSendCheckinEmail(),
+ 'qty' => 20,
+ ]);
+
+ return [$accessory, User::factory()->create()];
+ }
+
+ private function checkOut(Accessory $accessory, User $user, int $qty): void
+ {
+ $this->actingAs(User::factory()->superuser()->create())
+ ->post(route('accessories.checkout.store', $accessory), [
+ 'assigned_user' => $user->id,
+ 'checkout_to_type' => 'user',
+ 'checkout_qty' => $qty,
+ ])
+ ->assertRedirect();
+ }
+
+ private function checkOutSeat(License $license, User $user): LicenseSeat
+ {
+ $seat = $license->licenseseats()->whereNull('assigned_to')->whereNull('asset_id')->firstOrFail();
+
+ $this->actingAs(User::factory()->superuser()->create())
+ ->post(route('licenses.checkout.save', [$license->id, $seat->id]), [
+ 'assigned_to' => $user->id,
+ ])
+ ->assertRedirect();
+
+ return $seat->refresh();
+ }
+
+ private function oneHeldCheckoutOf(Accessory $accessory, User $user): int
+ {
+ return $accessory->checkouts()
+ ->where('assigned_type', User::class)
+ ->where('assigned_to', $user->id)
+ ->firstOrFail()
+ ->id;
+ }
+
+ private function checkIn(int $accessoryCheckoutId): void
+ {
+ $this->actingAs(User::factory()->superuser()->create())
+ ->post(route('accessories.checkin.store', $accessoryCheckoutId))
+ ->assertRedirect();
+ }
+
+ private function transfer(User $source, User $target, int $accessoryCheckoutId): void
+ {
+ $this->actingAs(User::factory()->superuser()->create())
+ ->post(route('users.transfer.store', $source), [
+ 'target_user_id' => $target->id,
+ 'note' => 'matrix',
+ 'accessory_checkout_ids' => [$accessoryCheckoutId],
+ ])
+ ->assertRedirect();
+ }
+
+ /**
+ * Accept one of the pair's pending rows, oldest first, returning it so the
+ * caller can prove it was left alone.
+ */
+ private function acceptPendingRow(Accessory $accessory, User $user, int $index): CheckoutAcceptance
+ {
+ $acceptance = $this->pendingRows($accessory, $user)->get($index);
+
+ $this->assertNotNull($acceptance, sprintf('No pending acceptance at index %d to accept.', $index));
+
+ $acceptance->accept('signature.png', 'the eula text as signed', 'accepted.pdf', 'matrix');
+
+ return $acceptance->refresh();
+ }
+
+ /** @return \Illuminate\Database\Eloquent\Collection<int, CheckoutAcceptance> */
+ private function pendingRows(Accessory $accessory, User $user)
+ {
+ return CheckoutAcceptance::pending()
+ ->where('checkoutable_type', Accessory::class)
+ ->where('checkoutable_id', $accessory->id)
+ ->where('assigned_to_id', $user->id)
+ ->orderBy('id')
+ ->get();
+ }
+
+ private function unitsHeld(Accessory $accessory, User $user): int
+ {
+ return $accessory->checkouts()
+ ->where('assigned_type', User::class)
+ ->where('assigned_to', $user->id)
+ ->count();
+ }
+
+ /** Null qty means one unit, as in AcceptanceController and LogListener. */
+ private function pendingQtySum(Accessory $accessory, User $user): int
+ {
+ return $this->pendingRows($accessory, $user)->sum(fn (CheckoutAcceptance $a) => $a->qty ?? 1);
+ }
+
+ private function acceptedQtySum(Accessory $accessory, User $user): int
+ {
+ return CheckoutAcceptance::whereNotNull('accepted_at')
+ ->where('checkoutable_type', Accessory::class)
+ ->where('checkoutable_id', $accessory->id)
+ ->where('assigned_to_id', $user->id)
+ ->get()
+ ->sum(fn (CheckoutAcceptance $a) => $a->qty ?? 1);
+ }
+
+ private function pendingRowCount(Accessory $accessory, User $user): int
+ {
+ return $this->pendingRowCountFor(Accessory::class, $accessory->id, $user);
+ }
+
+ private function pendingRowCountFor(string $type, int $id, User $user): int
+ {
+ return CheckoutAcceptance::pending()
+ ->where('checkoutable_type', $type)
+ ->where('checkoutable_id', $id)
+ ->where('assigned_to_id', $user->id)
+ ->count();
+ }
+
+ private function assertPendingQtyMatchesUnacceptedUnitsHeld(Accessory $accessory, User $user): void
+ {
+ $held = $this->unitsHeld($accessory, $user);
+ $accepted = $this->acceptedQtySum($accessory, $user);
+ $expected = max(0, $held - $accepted);
+ $pending = $this->pendingQtySum($accessory, $user);
+
+ $this->assertSame($expected, $pending, sprintf(
+ 'Invariant broken: user holds %d unit(s) with %d already accepted, so %d acknowledgement(s) should be outstanding — but pending acceptances total qty %d across %d row(s).',
+ $held,
+ $accepted,
+ $expected,
+ $pending,
+ $this->pendingRowCount($accessory, $user)
+ ));
+ }
+
+ /** An accepted row is the signed record: never renumber or remove it. */
+ private function assertAcceptedRowUntouched(CheckoutAcceptance $accepted, int $expectedQty): void
+ {
+ $row = CheckoutAcceptance::withTrashed()->find($accepted->id);
+
+ $this->assertNotNull($row, 'The accepted acceptance row was deleted.');
+ $this->assertNull($row->deleted_at, 'The accepted acceptance row was soft-deleted; accepted rows are history and must survive.');
+ $this->assertNotNull($row->accepted_at, 'The accepted acceptance row lost its accepted_at.');
+ $this->assertSame($expectedQty, (int) $row->qty, 'The accepted acceptance row was renumbered; its qty records what the user agreed to.');
+ $this->assertSame('the eula text as signed', $row->stored_eula, 'The accepted acceptance row lost the EULA text it was signed under.');
+ }
+}