lvl0/buckets
1
0
Fork 0
Code Issues 11 Pull requests 1 Projects Releases Packages Wiki Activity Actions

17 - Rewrite tests for phased distribution service

Browse source
This commit is contained in:
myrmidex 2026-03-21 23:55:21 +01:00
parent d45ca30151
commit 246ca69f40
2 changed files with 465 additions and 344 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

792
tests/Unit/PipelineAllocationServiceTest.php
View file

@ -3,6 +3,7 @@
namespace Tests\Unit;
use App\Enums\BucketAllocationTypeEnum;
use App\Enums\BucketTypeEnum;
use App\Models\Bucket;
use App\Models\Scenario;
use App\Services\Projection\PipelineAllocationService;
@ -24,389 +25,516 @@ protected function setUp(): void
$this->scenario = Scenario::factory()->create();
}
public function test_allocates_to_single_fixed_bucket()
// ──────────────────────────────────────────────────────
// Guard clauses
// ──────────────────────────────────────────────────────
public function test_returns_empty_collection_when_no_buckets(): void
{
// Arrange: Single bucket with $500 limit
$bucket = Bucket::factory()->create([
'scenario_id' => $this->scenario->id,
'name' => 'Emergency Fund',
'allocation_type' => BucketAllocationTypeEnum::FIXED_LIMIT,
'allocation_value' => 50000,
'starting_amount' => 0,
'priority' => 1,
]);
// Act: Allocate $300
$draws = $this->service->allocateInflow($this->scenario, 30000);
// Assert: All money goes to emergency fund
$this->assertCount(1, $draws);
$this->assertEquals($bucket->id, $draws[0]->bucket_id);
$this->assertEquals(30000, $draws[0]->amount);
}
public function test_allocates_across_multiple_fixed_buckets_by_priority()
{
// Arrange: Three buckets with different priorities
$bucket1 = Bucket::factory()->create([
'scenario_id' => $this->scenario->id,
'allocation_type' => BucketAllocationTypeEnum::FIXED_LIMIT,
'allocation_value' => 20000,
'starting_amount' => 0,
'priority' => 1,
]);
$bucket2 = Bucket::factory()->create([
'scenario_id' => $this->scenario->id,
'allocation_type' => BucketAllocationTypeEnum::FIXED_LIMIT,
'allocation_value' => 30000,
'starting_amount' => 0,
'priority' => 2,
]);
$bucket3 = Bucket::factory()->create([
'scenario_id' => $this->scenario->id,
'allocation_type' => BucketAllocationTypeEnum::FIXED_LIMIT,
'allocation_value' => 15000,
'starting_amount' => 0,
'priority' => 3,
]);
// Act: Allocate $550 (should fill bucket1 + bucket2 + partial bucket3)
$draws = $this->service->allocateInflow($this->scenario, 55000);
// Assert: Allocation follows priority order
$this->assertCount(3, $draws);
// Bucket 1: fully filled
$this->assertEquals($bucket1->id, $draws[0]->bucket_id);
$this->assertEquals(20000, $draws[0]->amount);
// Bucket 2: fully filled
$this->assertEquals($bucket2->id, $draws[1]->bucket_id);
$this->assertEquals(30000, $draws[1]->amount);
// Bucket 3: partially filled
$this->assertEquals($bucket3->id, $draws[2]->bucket_id);
$this->assertEquals(5000, $draws[2]->amount);
}
public function test_percentage_bucket_gets_percentage_of_remaining_amount()
{
// Arrange: Fixed bucket + percentage bucket
$fixedBucket = Bucket::factory()->create([
'scenario_id' => $this->scenario->id,
'allocation_type' => BucketAllocationTypeEnum::FIXED_LIMIT,
'allocation_value' => 30000,
'starting_amount' => 0,
'priority' => 1,
]);
$percentageBucket = Bucket::factory()->create([
'scenario_id' => $this->scenario->id,
'allocation_type' => BucketAllocationTypeEnum::PERCENTAGE,
'allocation_value' => 2000, // 20% in basis points
'starting_amount' => 0,
'priority' => 2,
]);
// Act: Allocate $1000
$draws = $this->service->allocateInflow($this->scenario, 100000);
// Assert: Fixed gets $300, percentage gets 20% of remaining $700 = $140
$this->assertCount(2, $draws);
$this->assertEquals(30000, $draws[0]->amount); // Fixed bucket
$this->assertEquals(14000, $draws[1]->amount); // 20% of $700
}
public function test_unlimited_bucket_gets_all_remaining_amount()
{
// Arrange: Fixed + unlimited buckets
$fixedBucket = Bucket::factory()->create([
'scenario_id' => $this->scenario->id,
'allocation_type' => BucketAllocationTypeEnum::FIXED_LIMIT,
'allocation_value' => 50000,
'starting_amount' => 0,
'priority' => 1,
]);
$unlimitedBucket = Bucket::factory()->create([
'scenario_id' => $this->scenario->id,
'allocation_type' => BucketAllocationTypeEnum::UNLIMITED,
'allocation_value' => null,
'starting_amount' => 0,
'priority' => 2,
]);
// Act: Allocate $1500
$draws = $this->service->allocateInflow($this->scenario, 150000);
// Assert: Fixed gets $500, unlimited gets remaining $1000
$this->assertCount(2, $draws);
$this->assertEquals(50000, $draws[0]->amount);
$this->assertEquals(100000, $draws[1]->amount);
}
public function test_skips_buckets_with_zero_allocation()
{
// Arrange: Bucket that can't accept any money
$fullBucket = Bucket::factory()->create([
'scenario_id' => $this->scenario->id,
'allocation_type' => BucketAllocationTypeEnum::FIXED_LIMIT,
'allocation_value' => 0, // No capacity
'starting_amount' => 0,
'priority' => 1,
]);
$normalBucket = Bucket::factory()->create([
'scenario_id' => $this->scenario->id,
'allocation_type' => BucketAllocationTypeEnum::FIXED_LIMIT,
'allocation_value' => 30000,
'starting_amount' => 0,
'priority' => 2,
]);
// Act: Allocate $200
$draws = $this->service->allocateInflow($this->scenario, 20000);
// Assert: Only normal bucket gets allocation
$this->assertCount(1, $draws);
$this->assertEquals($normalBucket->id, $draws[0]->bucket_id);
$this->assertEquals(20000, $draws[0]->amount);
}
public function test_handles_complex_mixed_bucket_scenario()
{
// Arrange: All bucket types in priority order
$fixed1 = Bucket::factory()->create([
'scenario_id' => $this->scenario->id,
'allocation_type' => BucketAllocationTypeEnum::FIXED_LIMIT,
'allocation_value' => 100000,
'starting_amount' => 0,
'priority' => 1,
]);
$percentage1 = Bucket::factory()->create([
'scenario_id' => $this->scenario->id,
'allocation_type' => BucketAllocationTypeEnum::PERCENTAGE,
'allocation_value' => 1500, // 15% in basis points
'starting_amount' => 0,
'priority' => 2,
]);
$fixed2 = Bucket::factory()->create([
'scenario_id' => $this->scenario->id,
'allocation_type' => BucketAllocationTypeEnum::FIXED_LIMIT,
'allocation_value' => 50000,
'starting_amount' => 0,
'priority' => 3,
]);
$percentage2 = Bucket::factory()->create([
'scenario_id' => $this->scenario->id,
'allocation_type' => BucketAllocationTypeEnum::PERCENTAGE,
'allocation_value' => 2500, // 25% in basis points
'starting_amount' => 0,
'priority' => 4,
]);
$unlimited = Bucket::factory()->create([
'scenario_id' => $this->scenario->id,
'allocation_type' => BucketAllocationTypeEnum::UNLIMITED,
'allocation_value' => null,
'starting_amount' => 0,
'priority' => 5,
]);
// Act: Allocate $5000
$draws = $this->service->allocateInflow($this->scenario, 500000);
// Assert: Complex allocation logic
$this->assertCount(5, $draws);
// Fixed1: gets $1000 (full capacity)
$this->assertEquals(100000, $draws[0]->amount);
// Percentage1: gets 15% of remaining $4000 = $600
$this->assertEquals(60000, $draws[1]->amount);
// Fixed2: gets $500 (full capacity)
$this->assertEquals(50000, $draws[2]->amount);
// Remaining after fixed allocations: $5000 - $1000 - $600 - $500 = $2900
// Percentage2: gets 25% of remaining $2900 = $725
$this->assertEquals(72500, $draws[3]->amount);
// Unlimited: gets remaining $2900 - $725 = $2175
$this->assertEquals(217500, $draws[4]->amount);
}
public function test_returns_empty_array_when_no_buckets()
{
// Act: Allocate to scenario with no buckets
$draws = $this->service->allocateInflow($this->scenario, 100000);
// Assert: No allocations made
$this->assertEmpty($draws);
}
public function test_returns_empty_array_when_amount_is_zero()
public function test_returns_empty_collection_when_amount_is_zero(): void
{
// Arrange: Create bucket
Bucket::factory()->create([
'scenario_id' => $this->scenario->id,
'allocation_type' => BucketAllocationTypeEnum::FIXED_LIMIT,
'allocation_value' => 50000,
'starting_amount' => 0,
'priority' => 1,
]);
$this->createNeedBucket(50000, priority: 1);
// Act: Allocate $0
$draws = $this->service->allocateInflow($this->scenario, 0);
// Assert: No allocations made
$this->assertEmpty($draws);
}
public function test_handles_negative_amount_gracefully()
public function test_returns_empty_collection_when_amount_is_negative(): void
{
// Arrange: Create bucket
Bucket::factory()->create([
'scenario_id' => $this->scenario->id,
'allocation_type' => BucketAllocationTypeEnum::FIXED_LIMIT,
'allocation_value' => 50000,
'starting_amount' => 0,
'priority' => 1,
]);
$this->createNeedBucket(50000, priority: 1);
// Act: Allocate negative amount
$draws = $this->service->allocateInflow($this->scenario, -10000);
// Assert: No allocations made
$this->assertEmpty($draws);
}
public function test_respects_bucket_priority_order()
// ──────────────────────────────────────────────────────
// Even mode — base phase
// ──────────────────────────────────────────────────────
public function test_even_mode_splits_evenly_across_need_buckets(): void
{
// Arrange: Buckets in non-sequential priority order
$bucket3 = Bucket::factory()->create([
'scenario_id' => $this->scenario->id,
'allocation_type' => BucketAllocationTypeEnum::FIXED_LIMIT,
'allocation_value' => 10000,
'starting_amount' => 0,
'priority' => 10, // Higher number
]);
$bucket1 = Bucket::factory()->create([
'scenario_id' => $this->scenario->id,
'allocation_type' => BucketAllocationTypeEnum::FIXED_LIMIT,
'allocation_value' => 20000,
'starting_amount' => 0,
'priority' => 1, // Lower number (higher priority)
]);
$bucket2 = Bucket::factory()->create([
'scenario_id' => $this->scenario->id,
'allocation_type' => BucketAllocationTypeEnum::FIXED_LIMIT,
'allocation_value' => 15000,
'starting_amount' => 0,
'priority' => 5, // Middle
]);
// 3 need buckets, $500 base each, $900 income → $300 each
$b1 = $this->createNeedBucket(50000, priority: 1);
$b2 = $this->createNeedBucket(50000, priority: 2);
$b3 = $this->createNeedBucket(50000, priority: 3);
// Act: Allocate $250
$draws = $this->service->allocateInflow($this->scenario, 25000);
$draws = $this->service->allocateInflow($this->scenario, 90000);
// Assert: Priority order respected (1, 5, 10)
$this->assertCount(2, $draws);
$this->assertEquals($bucket1->id, $draws[0]->bucket_id); // Priority 1 first
$this->assertEquals(20000, $draws[0]->amount);
$this->assertEquals($bucket2->id, $draws[1]->bucket_id); // Priority 5 second
$this->assertEquals(5000, $draws[1]->amount); // Partial fill
$this->assertCount(3, $draws);
$this->assertDrawAmount($draws, $b1->id, 30000);
$this->assertDrawAmount($draws, $b2->id, 30000);
$this->assertDrawAmount($draws, $b3->id, 30000);
}
public function test_percentage_allocation_with_insufficient_remaining_amount()
public function test_even_mode_redistributes_when_bucket_fills_up(): void
{
// Arrange: Large fixed bucket + percentage bucket
$fixedBucket = Bucket::factory()->create([
'scenario_id' => $this->scenario->id,
'allocation_type' => BucketAllocationTypeEnum::FIXED_LIMIT,
'allocation_value' => 95000,
'starting_amount' => 0,
'priority' => 1,
]);
$percentageBucket = Bucket::factory()->create([
'scenario_id' => $this->scenario->id,
'allocation_type' => BucketAllocationTypeEnum::PERCENTAGE,
'allocation_value' => 2000, // 20% in basis points
'starting_amount' => 0,
'priority' => 2,
]);
// Bucket A: $200 base, Bucket B: $500 base, Bucket C: $500 base
// $900 income → even share = $300 each → A caps at $200, excess $100 redistributed
// B and C get $300 + $50 = $350 each
$a = $this->createNeedBucket(20000, priority: 1);
$b = $this->createNeedBucket(50000, priority: 2);
$c = $this->createNeedBucket(50000, priority: 3);
// Act: Allocate $1000 (only $50 left after fixed)
$draws = $this->service->allocateInflow($this->scenario, 100000);
$draws = $this->service->allocateInflow($this->scenario, 90000);
// Assert: Percentage gets 20% of remaining $50 = $10
$this->assertCount(2, $draws);
$this->assertEquals(95000, $draws[0]->amount);
$this->assertEquals(1000, $draws[1]->amount); // 20% of $50
$this->assertCount(3, $draws);
$this->assertDrawAmount($draws, $a->id, 20000);
$this->assertDrawAmount($draws, $b->id, 35000);
$this->assertDrawAmount($draws, $c->id, 35000);
}
public function test_fixed_allocation_respects_buffer_multiplier(): void
public function test_even_mode_needs_filled_before_wants(): void
{
Bucket::factory()->create([
'scenario_id' => $this->scenario->id,
'allocation_type' => BucketAllocationTypeEnum::FIXED_LIMIT,
'allocation_value' => 50000,
'buffer_multiplier' => 1.0,
'starting_amount' => 0,
'priority' => 1,
]);
// 2 need buckets ($500 base each), 1 want bucket ($500 base)
// $800 income → needs get $400 each (even split), wants get $0
$n1 = $this->createNeedBucket(50000, priority: 1);
$n2 = $this->createNeedBucket(50000, priority: 2);
$w1 = $this->createWantBucket(50000, priority: 3);
// Effective capacity = 50000 * (1 + 1.0) = 100000
$draws = $this->service->allocateInflow($this->scenario, 100000);
$this->assertCount(1, $draws);
$this->assertEquals(100000, $draws[0]->amount);
}
public function test_fixed_allocation_with_buffer_partially_filled(): void
{
$bucket = Bucket::factory()->create([
'scenario_id' => $this->scenario->id,
'allocation_type' => BucketAllocationTypeEnum::FIXED_LIMIT,
'allocation_value' => 50000,
'buffer_multiplier' => 1.0,
'starting_amount' => 30000,
'priority' => 1,
]);
// Effective capacity = 100000, balance = 30000, available = 70000
$draws = $this->service->allocateInflow($this->scenario, 80000);
$this->assertCount(1, $draws);
$this->assertEquals(70000, $draws[0]->amount);
$this->assertCount(2, $draws);
$this->assertDrawAmount($draws, $n1->id, 40000);
$this->assertDrawAmount($draws, $n2->id, 40000);
}
public function test_buffer_does_not_affect_percentage_allocation(): void
public function test_even_mode_wants_filled_after_needs_base(): void
{
// 1 need ($300 base), 2 wants ($500 base each)
// $1000 income → need gets $300 (base), wants split remaining $700 = $350 each
$n = $this->createNeedBucket(30000, priority: 1);
$w1 = $this->createWantBucket(50000, priority: 2);
$w2 = $this->createWantBucket(50000, priority: 3);
$draws = $this->service->allocateInflow($this->scenario, 100000);
$this->assertCount(3, $draws);
$this->assertDrawAmount($draws, $n->id, 30000);
$this->assertDrawAmount($draws, $w1->id, 35000);
$this->assertDrawAmount($draws, $w2->id, 35000);
}
public function test_even_mode_remainder_cents_go_to_highest_priority(): void
{
// 3 need buckets, $500 base each, $100 income → $33/$33/$34 or similar
// intdiv(10000, 3) = 3333, remainder = 1 → first bucket gets 3334
$b1 = $this->createNeedBucket(50000, priority: 1);
$b2 = $this->createNeedBucket(50000, priority: 2);
$b3 = $this->createNeedBucket(50000, priority: 3);
$draws = $this->service->allocateInflow($this->scenario, 10000);
$this->assertCount(3, $draws);
$this->assertDrawAmount($draws, $b1->id, 3334);
$this->assertDrawAmount($draws, $b2->id, 3333);
$this->assertDrawAmount($draws, $b3->id, 3333);
}
public function test_even_mode_fewer_cents_than_buckets(): void
{
// 3 need buckets, 2 cents income → first 2 get 1 cent each, third gets nothing
$b1 = $this->createNeedBucket(50000, priority: 1);
$b2 = $this->createNeedBucket(50000, priority: 2);
$b3 = $this->createNeedBucket(50000, priority: 3);
$draws = $this->service->allocateInflow($this->scenario, 2);
$this->assertCount(2, $draws);
$this->assertDrawAmount($draws, $b1->id, 1);
$this->assertDrawAmount($draws, $b2->id, 1);
}
// ──────────────────────────────────────────────────────
// Priority mode — base phase
// ──────────────────────────────────────────────────────
public function test_priority_mode_fills_highest_priority_first(): void
{
$scenario = Scenario::factory()->priority()->create();
$n1 = $this->createNeedBucket(50000, priority: 1, scenarioId: $scenario->id);
$n2 = $this->createNeedBucket(50000, priority: 2, scenarioId: $scenario->id);
$w1 = $this->createWantBucket(50000, priority: 3, scenarioId: $scenario->id);
// $800 → need1 gets $500, need2 gets $300, want gets $0
$draws = $this->service->allocateInflow($scenario, 80000);
$this->assertCount(2, $draws);
$this->assertDrawAmount($draws, $n1->id, 50000);
$this->assertDrawAmount($draws, $n2->id, 30000);
}
public function test_priority_mode_needs_before_wants(): void
{
$scenario = Scenario::factory()->priority()->create();
$n1 = $this->createNeedBucket(50000, priority: 1, scenarioId: $scenario->id);
$n2 = $this->createNeedBucket(30000, priority: 2, scenarioId: $scenario->id);
$w1 = $this->createWantBucket(50000, priority: 3, scenarioId: $scenario->id);
// $1000 → need1 $500, need2 $300, want1 gets remaining $200
$draws = $this->service->allocateInflow($scenario, 100000);
$this->assertCount(3, $draws);
$this->assertDrawAmount($draws, $n1->id, 50000);
$this->assertDrawAmount($draws, $n2->id, 30000);
$this->assertDrawAmount($draws, $w1->id, 20000);
}
// ──────────────────────────────────────────────────────
// Buffer phases
// ──────────────────────────────────────────────────────
public function test_base_filled_before_buffer(): void
{
// Need: $500 base, 0.5x buffer → $750 effective capacity
// $2000 income → base phase: $500, buffer phase: $250, overflow: $1250
$n = $this->createNeedBucket(50000, priority: 1, buffer: 0.5);
$overflow = $this->createOverflowBucket(priority: 2);
$draws = $this->service->allocateInflow($this->scenario, 200000);
$this->assertCount(2, $draws);
$this->assertDrawAmount($draws, $n->id, 75000); // base $500 + buffer $250
$this->assertDrawAmount($draws, $overflow->id, 125000);
}
public function test_need_buffer_filled_before_want_buffer(): void
{
// Need: $500 base, 1x buffer → $1000 effective
// Want: $500 base, 1x buffer → $1000 effective
// $1800 → need base $500, want base $500, need buffer $500, want gets $300 buffer
$n = $this->createNeedBucket(50000, priority: 1, buffer: 1.0);
$w = $this->createWantBucket(50000, priority: 2, buffer: 1.0);
$draws = $this->service->allocateInflow($this->scenario, 180000);
$this->assertCount(2, $draws);
$this->assertDrawAmount($draws, $n->id, 100000); // full: base + buffer
$this->assertDrawAmount($draws, $w->id, 80000); // base $500 + $300 buffer
}
public function test_priority_mode_buffer_fills_by_priority(): void
{
$scenario = Scenario::factory()->priority()->create();
// Need1: $300 base, 1x buffer → $600 effective
// Need2: $300 base, 1x buffer → $600 effective
// $1000 income
$n1 = $this->createNeedBucket(30000, priority: 1, buffer: 1.0, scenarioId: $scenario->id);
$n2 = $this->createNeedBucket(30000, priority: 2, buffer: 1.0, scenarioId: $scenario->id);
$draws = $this->service->allocateInflow($scenario, 100000);
// Phase 1 (needs base, priority): n1=$300, n2=$300, remaining=$400
// Phase 3 (needs buffer, priority): n1 buffer=$300, n2 gets $100, remaining=$0
$this->assertCount(2, $draws);
$this->assertDrawAmount($draws, $n1->id, 60000); // full base + full buffer
$this->assertDrawAmount($draws, $n2->id, 40000); // full base + $100 buffer
}
public function test_no_buffer_when_multiplier_is_zero(): void
{
// Need: $500 base, 0x buffer → $500 effective
// $800 → need gets $500, overflow gets $300
$n = $this->createNeedBucket(50000, priority: 1, buffer: 0);
$overflow = $this->createOverflowBucket(priority: 2);
$draws = $this->service->allocateInflow($this->scenario, 80000);
$this->assertCount(2, $draws);
$this->assertDrawAmount($draws, $n->id, 50000);
$this->assertDrawAmount($draws, $overflow->id, 30000);
}
public function test_partially_filled_bucket_respects_existing_balance(): void
{
// Need: $500 base, already has $300 → only $200 space in base phase
$n = $this->createNeedBucket(50000, priority: 1, startingAmount: 30000);
$overflow = $this->createOverflowBucket(priority: 2);
$draws = $this->service->allocateInflow($this->scenario, 80000);
$this->assertCount(2, $draws);
$this->assertDrawAmount($draws, $n->id, 20000);
$this->assertDrawAmount($draws, $overflow->id, 60000);
}
// ──────────────────────────────────────────────────────
// Overflow
// ──────────────────────────────────────────────────────
public function test_overflow_captures_remainder(): void
{
$n = $this->createNeedBucket(30000, priority: 1);
$overflow = $this->createOverflowBucket(priority: 2);
$draws = $this->service->allocateInflow($this->scenario, 100000);
$this->assertCount(2, $draws);
$this->assertDrawAmount($draws, $n->id, 30000);
$this->assertDrawAmount($draws, $overflow->id, 70000);
}
public function test_all_buckets_full_everything_to_overflow(): void
{
$n = $this->createNeedBucket(10000, priority: 1, startingAmount: 10000); // already full
$w = $this->createWantBucket(10000, priority: 2, startingAmount: 10000); // already full
$overflow = $this->createOverflowBucket(priority: 3);
$draws = $this->service->allocateInflow($this->scenario, 50000);
$this->assertCount(1, $draws);
$this->assertDrawAmount($draws, $overflow->id, 50000);
}
// ──────────────────────────────────────────────────────
// Edge cases
// ──────────────────────────────────────────────────────
public function test_no_need_buckets_goes_straight_to_wants(): void
{
$w1 = $this->createWantBucket(50000, priority: 1);
$w2 = $this->createWantBucket(50000, priority: 2);
$draws = $this->service->allocateInflow($this->scenario, 60000);
$this->assertCount(2, $draws);
$this->assertDrawAmount($draws, $w1->id, 30000);
$this->assertDrawAmount($draws, $w2->id, 30000);
}
public function test_single_need_bucket_gets_all_up_to_capacity(): void
{
$n = $this->createNeedBucket(50000, priority: 1);
$draws = $this->service->allocateInflow($this->scenario, 30000);
$this->assertCount(1, $draws);
$this->assertDrawAmount($draws, $n->id, 30000);
}
public function test_allocates_to_single_need_bucket_with_buffer(): void
{
// $500 base, 1x buffer → $1000 effective, $1000 income → gets all
$n = $this->createNeedBucket(50000, priority: 1, buffer: 1.0);
$draws = $this->service->allocateInflow($this->scenario, 100000);
$this->assertCount(1, $draws);
$this->assertDrawAmount($draws, $n->id, 100000);
}
public function test_skips_buckets_with_zero_allocation_value(): void
{
$zero = $this->createNeedBucket(0, priority: 1);
$normal = $this->createNeedBucket(30000, priority: 2);
$draws = $this->service->allocateInflow($this->scenario, 20000);
$this->assertCount(1, $draws);
$this->assertDrawAmount($draws, $normal->id, 20000);
}
public function test_non_fixed_limit_buckets_are_skipped_in_phases(): void
{
// Percentage bucket as need → gets nothing (no meaningful cap in phased distribution)
Bucket::factory()->create([
'scenario_id' => $this->scenario->id,
'type' => BucketTypeEnum::NEED,
'allocation_type' => BucketAllocationTypeEnum::PERCENTAGE,
'allocation_value' => 2500, // 25% in basis points
'buffer_multiplier' => 1.0,
'allocation_value' => 2500,
'starting_amount' => 0,
'priority' => 1,
]);
$overflow = $this->createOverflowBucket(priority: 2);
$draws = $this->service->allocateInflow($this->scenario, 100000);
$draws = $this->service->allocateInflow($this->scenario, 50000);
$this->assertCount(1, $draws);
$this->assertEquals(25000, $draws[0]->amount); // 25% of 100000
$this->assertDrawAmount($draws, $overflow->id, 50000);
}
public function test_buffer_does_not_affect_unlimited_allocation(): void
public function test_surplus_is_lost_when_no_overflow_bucket(): void
{
Bucket::factory()->create([
'scenario_id' => $this->scenario->id,
'allocation_type' => BucketAllocationTypeEnum::UNLIMITED,
'allocation_value' => null,
'buffer_multiplier' => 1.0,
'starting_amount' => 0,
'priority' => 1,
]);
// $500 income, only $300 capacity → $200 surplus has nowhere to go
$n = $this->createNeedBucket(30000, priority: 1);
$draws = $this->service->allocateInflow($this->scenario, 100000);
$draws = $this->service->allocateInflow($this->scenario, 50000);
$this->assertCount(1, $draws);
$this->assertEquals(100000, $draws[0]->amount);
$this->assertDrawAmount($draws, $n->id, 30000);
// Remaining $200 is silently dropped — no overflow bucket to catch it
}
public function test_priority_order_respected_regardless_of_creation_order(): void
{
$scenario = Scenario::factory()->priority()->create();
// Create in reverse priority order
$b3 = $this->createNeedBucket(10000, priority: 10, scenarioId: $scenario->id);
$b1 = $this->createNeedBucket(20000, priority: 1, scenarioId: $scenario->id);
$b2 = $this->createNeedBucket(15000, priority: 5, scenarioId: $scenario->id);
$draws = $this->service->allocateInflow($scenario, 25000);
$this->assertCount(2, $draws);
$this->assertDrawAmount($draws, $b1->id, 20000);
$this->assertDrawAmount($draws, $b2->id, 5000);
}
// ──────────────────────────────────────────────────────
// Full pipeline integration
// ──────────────────────────────────────────────────────
public function test_full_pipeline_even_mode(): void
{
// Need1: $500 base, 0.5x buffer → $750 effective
// Need2: $200 base, no buffer → $200 effective
// Want1: $400 base, no buffer → $400 effective
// Overflow
// $900 income — not enough to fill everything
$n1 = $this->createNeedBucket(50000, priority: 1, buffer: 0.5);
$n2 = $this->createNeedBucket(20000, priority: 2);
$w1 = $this->createWantBucket(40000, priority: 3);
$overflow = $this->createOverflowBucket(priority: 4);
$draws = $this->service->allocateInflow($this->scenario, 90000);
// Phase 1 (needs base, even): n1=$500 (capped), n2=$200 (capped), remaining=$200
// Phase 2 (wants base, even): w1=$200 (partial of $400), remaining=$0
$this->assertCount(3, $draws);
$this->assertDrawAmount($draws, $n1->id, 50000); // $500 base
$this->assertDrawAmount($draws, $n2->id, 20000); // $200 base
$this->assertDrawAmount($draws, $w1->id, 20000); // partial $200 of $400
}
public function test_full_pipeline_priority_mode(): void
{
$scenario = Scenario::factory()->priority()->create();
// Need1: $500 base, 0.5x buffer → $750 effective
// Need2: $400 base, no buffer → $400 effective
// Want1: $300 base, no buffer → $300 effective
// Overflow
// $600 income — not enough to fill all need bases
$n1 = $this->createNeedBucket(50000, priority: 1, buffer: 0.5, scenarioId: $scenario->id);
$n2 = $this->createNeedBucket(40000, priority: 2, scenarioId: $scenario->id);
$w1 = $this->createWantBucket(30000, priority: 3, scenarioId: $scenario->id);
$overflow = $this->createOverflowBucket(priority: 4, scenarioId: $scenario->id);
$draws = $this->service->allocateInflow($scenario, 60000);
// Phase 1 (needs base, priority): n1=$500, n2=$100, remaining=$0
// Even mode would split $600/2=$300 each — priority concentrates on n1 first
$this->assertCount(2, $draws);
$this->assertDrawAmount($draws, $n1->id, 50000);
$this->assertDrawAmount($draws, $n2->id, 10000);
}
public function test_even_and_priority_modes_produce_different_results(): void
{
// 2 need buckets: $500 and $300 base, $600 income
// Even: $300 each → both fit. n1=$300, n2=$300.
// Priority: n1 gets $500, n2 gets $100.
$n1Even = $this->createNeedBucket(50000, priority: 1);
$n2Even = $this->createNeedBucket(30000, priority: 2);
$evenDraws = $this->service->allocateInflow($this->scenario, 60000);
$this->assertCount(2, $evenDraws);
$this->assertDrawAmount($evenDraws, $n1Even->id, 30000); // even: $300 each
$this->assertDrawAmount($evenDraws, $n2Even->id, 30000);
// Same setup with priority mode
$priorityScenario = Scenario::factory()->priority()->create();
$n1Prio = $this->createNeedBucket(50000, priority: 1, scenarioId: $priorityScenario->id);
$n2Prio = $this->createNeedBucket(30000, priority: 2, scenarioId: $priorityScenario->id);
$prioDraws = $this->service->allocateInflow($priorityScenario, 60000);
$this->assertCount(2, $prioDraws);
$this->assertDrawAmount($prioDraws, $n1Prio->id, 50000); // priority: fills first
$this->assertDrawAmount($prioDraws, $n2Prio->id, 10000); // gets remainder
}
public function test_full_pipeline_flows_through_all_five_phases(): void
{
// Need: $200 base, 1x buffer → $400 effective
// Want: $100 base, 1x buffer → $200 effective
// Overflow
// $800 income → enough to fill everything and hit overflow
$n = $this->createNeedBucket(20000, priority: 1, buffer: 1.0);
$w = $this->createWantBucket(10000, priority: 2, buffer: 1.0);
$overflow = $this->createOverflowBucket(priority: 3);
$draws = $this->service->allocateInflow($this->scenario, 80000);
// Phase 1 (needs base): n=$200, remaining=$600
// Phase 2 (wants base): w=$100, remaining=$500
// Phase 3 (needs buffer): n=$200 buffer, remaining=$300
// Phase 4 (wants buffer): w=$100 buffer, remaining=$200
// Phase 5 (overflow): $200
$this->assertCount(3, $draws);
$this->assertDrawAmount($draws, $n->id, 40000); // $200 base + $200 buffer
$this->assertDrawAmount($draws, $w->id, 20000); // $100 base + $100 buffer
$this->assertDrawAmount($draws, $overflow->id, 20000); // remainder
}
// ──────────────────────────────────────────────────────
// Helpers
// ──────────────────────────────────────────────────────
private function createNeedBucket(
int $allocationValue,
int $priority,
float $buffer = 0,
int $startingAmount = 0,
?int $scenarioId = null,
): Bucket {
return Bucket::factory()->need()->fixedLimit($allocationValue)->create([
'scenario_id' => $scenarioId ?? $this->scenario->id,
'priority' => $priority,
'buffer_multiplier' => $buffer,
'starting_amount' => $startingAmount,
]);
}
private function createWantBucket(
int $allocationValue,
int $priority,
float $buffer = 0,
int $startingAmount = 0,
?int $scenarioId = null,
): Bucket {
return Bucket::factory()->want()->fixedLimit($allocationValue)->create([
'scenario_id' => $scenarioId ?? $this->scenario->id,
'priority' => $priority,
'buffer_multiplier' => $buffer,
'starting_amount' => $startingAmount,
]);
}
private function createOverflowBucket(int $priority, ?int $scenarioId = null): Bucket
{
return Bucket::factory()->overflow()->create([
'scenario_id' => $scenarioId ?? $this->scenario->id,
'priority' => $priority,
]);
}
private function assertDrawAmount($draws, int $bucketId, int $expectedAmount): void
{
$draw = $draws->first(fn ($d) => $d->bucket_id === $bucketId);
$this->assertNotNull($draw, "No draw found for bucket {$bucketId}");
$this->assertEquals($expectedAmount, $draw->amount, "Draw amount mismatch for bucket {$bucketId}");
}
}

17
tests/Unit/ProjectionGeneratorServiceTest.php
View file

@ -99,18 +99,14 @@ public function test_generates_weekly_expense_stream_projections()
public function test_allocates_income_immediately_to_buckets()
{
// Arrange: Income stream and buckets with priority
$bucket1 = Bucket::factory()->create([
$bucket1 = Bucket::factory()->need()->fixedLimit(30000)->create([
'scenario_id' => $this->scenario->id,
'allocation_type' => BucketAllocationTypeEnum::FIXED_LIMIT,
'allocation_value' => 30000,
'starting_amount' => 0,
'priority' => 1,
]);
$bucket2 = Bucket::factory()->create([
$bucket2 = Bucket::factory()->overflow()->create([
'scenario_id' => $this->scenario->id,
'allocation_type' => BucketAllocationTypeEnum::UNLIMITED,
'allocation_value' => null,
'starting_amount' => 0,
'priority' => 2,
]);
@ -196,9 +192,8 @@ public function test_handles_monthly_streams_correctly()
public function test_processes_multiple_streams_on_same_day()
{
// Arrange: Two income streams that fire on the same day
$bucket = Bucket::factory()->create([
$bucket = Bucket::factory()->overflow()->create([
'scenario_id' => $this->scenario->id,
'allocation_type' => BucketAllocationTypeEnum::UNLIMITED,
'starting_amount' => 0,
'priority' => 1,
]);
@ -235,9 +230,8 @@ public function test_processes_multiple_streams_on_same_day()
public function test_handles_mixed_income_and_expense_streams()
{
// Arrange: Income and expense streams
$bucket = Bucket::factory()->create([
$bucket = Bucket::factory()->overflow()->create([
'scenario_id' => $this->scenario->id,
'allocation_type' => BucketAllocationTypeEnum::UNLIMITED,
'starting_amount' => 0,
'priority' => 1,
]);
@ -277,9 +271,8 @@ public function test_handles_mixed_income_and_expense_streams()
public function test_summary_calculations_are_accurate()
{
// Arrange: Income and expense streams
$bucket = Bucket::factory()->create([
$bucket = Bucket::factory()->overflow()->create([
'scenario_id' => $this->scenario->id,
'allocation_type' => BucketAllocationTypeEnum::UNLIMITED,
'starting_amount' => 0,
'priority' => 1,
]);