Skip to content

A free open source IT asset/license management system

23.5 KB
Raw Blame
<?php

namespace Tests\Feature\CheckoutAcceptances;

use App\Models\Accessory;
use App\Models\AccessoryCheckout;
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\Location;
use App\Models\User;
use Illuminate\Support\Facades\DB;
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);
    }

    #[Test]
    public function checking_in_a_location_held_unit_leaves_a_users_acceptance_alone(): void
    {
        [$accessory, $user] = $this->accessoryAndUser();
        $this->checkOut($accessory, $user, qty: 2);

        // Acceptances only ever belong to users, so assigned_to_id holds a user
        // id. An accessory can be held by a user and a location at once, so a
        // location id equal to a user id must not match that user's rows.
        $location = $this->locationWithIdCollidingWith($user);

        $locationCheckout = AccessoryCheckout::create([
            'accessory_id' => $accessory->id,
            'assigned_to' => $location->id,
            'assigned_type' => Location::class,
            'created_by' => User::factory()->create()->id,
        ]);

        $this->checkIn($locationCheckout->id);

        $this->assertSame(2, $this->unitsHeld($accessory, $user), 'The user\'s own units were not touched.');
        $this->assertSame(2, $this->pendingQtySum($accessory, $user),
            'Checking in a location-held unit cleared the user\'s acceptance by id collision.');
    }

    // ─────────────────────────────────────────────────────────────────────
    // 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_user' => $user->id,
            ])
            ->assertRedirect();

        $seat->refresh();

        $this->assertSame(
            $user->id,
            $seat->assigned_to,
            'The seat was not checked out as expected.'
        );

        return $seat;
    }

    /**
     * Ids are per-table, so a location sharing a user's id is ordinary in
     * production but has to be forced here.
     */
    private function locationWithIdCollidingWith(User $user): Location
    {
        $location = Location::factory()->create();
        DB::table('locations')->where('id', $location->id)->update(['id' => $user->id]);

        return Location::findOrFail($user->id);
    }

    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.');
    }
}