Add exact ratio distribution for deterministic test data generation by layoutd · Pull Request #186 · woocommerce/wc-smooth-generator

layoutd · 2025-10-27T13:18:45Z

NOTE: This PR branches from #182 and will need merge conflict resolution with #184 and #185 (all modify the batch() method). The conflicts are trivial - just combining initialization calls.

Builds on: #182

Summary

Adds exact ratio distribution for coupon and refund generation in batch mode, eliminating variance from probabilistic distribution. Also includes critical bug fixes for weighted selection and counter restoration.

Current Behavior (Probabilistic)

With 100 orders at 0.5 coupon ratio:

❌ Get 45-55 coupons (varies due to random chance)
❌ Can't predict exact counts for testing

New Behavior (Deterministic)

With 100 orders at 0.5 coupon ratio:

✅ Get exactly 50 coupons (pre-calculated distribution)
✅ Predictable counts for testing and verification

Key Changes

Exact Ratio Distribution - Pre-generates boolean/integer arrays with exact counts before shuffling
Fixed Weighted Selection Bug - Corrected threshold calculation that was causing incorrect distribution
Counter Restoration - Restores orders_remaining and distribution arrays when order generation fails

Benefits

Deterministic Testing - Exact ratios make test verification trivial
No Variance - Eliminates probabilistic randomness in batch operations
Backwards Compatible - Single orders still use probabilistic approach
Memory Efficient - Integer constants instead of strings for large batches
Correct Distribution - Fixed threshold bug ensures ratios work as expected

Testing

# Test exact coupon ratio
ddev wp wc generate orders 100 --coupon-ratio=0.5 --status=completed
# Verify: Query wp_wc_orders_meta for _coupon_lines_hash, should be exactly 50

# Test exact refund ratio  
ddev wp wc generate orders 100 --status=completed --refund-ratio=0.4
# Verify: Should have exactly 20 full, 10 partial, 10 multi-partial refunds (40 total)

# Test counter restoration on failure
ddev wp wc generate orders 100 --coupon-ratio=0.5 --refund-ratio=0.4
# Intentionally cause some failures, verify counters restore correctly

Original Implementation Details

Coupon Distribution

Pre-generates an array of boolean flags:

// 100 orders, 0.5 ratio → exactly 50 true, 50 false
[true, true, ..., false, false]
shuffle($flags);

Odd number handling: Uses round() for non-exact splits:

11 orders @ 0.5 ratio → round(11 × 0.5) = round(5.5) = 6 with coupons, 5 without

Refund Distribution

Pre-generates refund type flags with exact split using integer constants for memory efficiency:

// Integer constants for memory optimization
const REFUND_TYPE_NONE = 0;
const REFUND_TYPE_FULL = 1;
const REFUND_TYPE_PARTIAL = 2;
const REFUND_TYPE_MULTI = 3;

// 100 orders, 0.4 refund ratio → 40 refunds total:
// - 20 full (50%)
// - 10 single partial (25%)
// - 10 multi-partial (25%)
[1, 1, ..., 2, 2, ..., 3, 3, ..., 0, 0, ...]
shuffle($flags);

Odd number handling: Remainder goes to multi-partial:

11 orders @ 0.4 ratio → 4 total refunds (rounded)
- round(4 × 0.5) = 2 full
- round(4 × 0.25) = 1 partial
- 4 - 2 - 1 = 1 multi (remainder)
- 11 - 4 = 7 none

Memory efficiency: For 20,000 orders, integers use ~160 KB vs strings ~160-320 KB, plus better CPU cache locality.

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

…rovided

- Add detailed logging when orders cannot be refunded due to empty line items - Consolidate refund creation error logs into single formatted message - Add error logging for invalid order instance check These improvements will help diagnose why some completed orders aren't receiving refunds when --refund-ratio=1.0 is specified. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>

Adds check to ensure refund amount is greater than 0 before calling wc_create_refund(). This prevents "Invalid refund amount" errors that occur when: - Orders have 100% discount coupons (total = $0) - Line items have $0 totals - Calculation results in 0 or negative amount Logs order ID, calculated amount, and order total when skipping refund. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>

The "Invalid refund amount" error occurred because calculated refund amounts slightly exceeded the available order total due to rounding errors in tax calculations. Changes: - Calculate maximum refundable amount (order total - already refunded) - Cap refund amount to maximum available before calling wc_create_refund() - Round both calculated refund and max refund to 2 decimal places - Improve error logging to show order total and already refunded amounts Example of the issue: - Order total: $24851.03 - Calculated refund (with 3 decimal tax): $24851.04 - Result: $0.01 over limit → "Invalid refund amount" error This fix ensures refunds never exceed the mathematically available amount, preventing WooCommerce validation errors. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>

…partial refunds stay under 50% For full refunds, use the order's actual total instead of summing line items to avoid rounding discrepancies that created tiny 0.01 refunds. For partial refunds, ensure the total stays below 50% of the order total by removing items if needed, preventing two partial refunds from fully refunding an order. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>

…tribution

…tion

…before applying --coupons flag

…tion

chihsuan

Great work on this feature! @layoutd Confirmed that coupons/refunds are generated correctly. 👍

I wanted to add a potential enhancement to this feature. Instead of pre-generating arrays, maybe we can calculate probability dynamically using "selection without replacement", something like this:

  // Initialize counters (O(1) memory)
  $coupons_remaining = isset( $args['coupon-ratio'] )
      ? (int) round( $amount * floatval( $args['coupon-ratio'] ) )
      : 0;
  $orders_remaining = $amount;

  for ( $i = 1; $i <= $amount; $i++ ) {
      $include_coupon = null;

      if ( isset( $args['coupon-ratio'] ) ) {
          // Probability = remaining_coupons / remaining_orders
          // Guarantees exact count while maintaining random distribution
          $include_coupon = ( wp_rand( 1, $orders_remaining ) <= $coupons_remaining );
          if ( $include_coupon ) {
              $coupons_remaining--;
          }
      }

      $orders_remaining--;

      // ... generate order
  }

The approach might be worth considering for the elimination threshold.

layoutd · 2026-02-04T12:27:26Z

Thanks for the suggestion @chihsuan, I've implemented the changes to improve . As a follow-up PR, it would be interesting to add unit tests to cover all generation and edge cases.

layoutd and others added 30 commits October 23, 2025 01:13

Add --coupon-ratio parameter to order generator

161c802

Add --refund-ratio parameter to order generator

df0fda0

Improve refund logic to properly handle line items and fees

4d3eb9d

Fix refund tax calculation to properly handle tax rate IDs

4dd4a96

Calculate explicit refund amount from line items

84a81bc

Fix refund ratio logic and add multiple refund support

368e5b7

Update partial refund reason to show products and items

479a1a8

Force partial refunds for orders with existing refunds

4f98a67

Recalculate order totals after applying coupon

a3e1536

Update includes/Generator/Order.php

74ae8e1

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Doc update

e2494ec

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Fix array_rand edge case for orders with exactly 2 items

ff277e2

Refactor coupon creation to use Coupon::generate()

f80b01e

Move coupon retrieval logic to Coupon::get_random()

ee9ff32

Use WordPress get_posts() API instead of raw SQL queries

07daacb

Add discount_type parameter to Coupon generator

57daab8

Refactor Order generator to use Coupon::batch()

24b2493

Add discount_type parameter to CLI coupon command

f8d718c

Update README with new coupon and order parameters

080ee99

Clarify that refunds are split evenly between partial and full

b9c85f9

Fix backwards compatibility: only set discount_type when explicitly p…

86a499c

…rovided

Add input validation for coupon-ratio and refund-ratio parameters

2c9940e

Add performance comment for get_posts() in Coupon::get_random()

5b53925

Clarify that --coupons flag is equivalent to --coupon-ratio=1.0

0816747

Fix ratio probability calculation using integer-based random generation

0f5dd77

Add check to prevent refunds with empty line items

f69d126

layoutd added 6 commits October 30, 2025 01:37

Use floor() instead of round() to avoid double rounding in refund dis…

a033f04

…tribution

Simplify status check in init_ratio_flags using null coalescing

da23c52

Add batch size threshold constant for memory management

91f6f06

Implement threshold-based fallback for large batch operations

eeed7d5

Add documentation and user notification for memory-based fallback

f699246

Add explicit bounds checking and error logging for batch index arrays

65ba0a0

layoutd marked this pull request as ready for review October 30, 2025 00:53

Base automatically changed from add-order-coupon-refund-ratios to trunk October 30, 2025 12:33

layoutd added 10 commits October 30, 2025 15:54

Merge remote-tracking branch 'origin/trunk' into exact-ratio-distribu…

a02ee68

…tion

Merge branch 'trunk' into exact-ratio-distribution

f2b9ff9

Remove static properties

038deb7

Update legacy coupon handling in Order generator to check batch mode …

fa9c16f

…before applying --coupons flag

Restore boolean casts for semantic clarity

1156090

Add coupon parameter precedence documentation

0137d99

Improve threshold messaging with warnings and error_log

8978ef3

Add comprehensive testing guide for exact ratio distribution

ec3c65a

Update README with deterministic distribution documentation

81b6246

Merge remote-tracking branch 'origin/trunk' into exact-ratio-distribu…

8129f2c

…tion

chihsuan approved these changes Feb 4, 2026

View reviewed changes

layoutd added 8 commits February 4, 2026 11:25

Use dynamic counters for coupon distribution

9f6ad3e

Use dynamic counters for refund distribution

782f292

Remove obsolete flag generation methods and threshold

aafdcf6

Update README for unlimited batch sizes

16fc6ea

Update TESTING.md to remove threshold tests

e683e17

Fix weighted selection threshold bug

9702d7d

Restore counters when order generation fails

32320bc

Also restore orders_remaining counter on failure

ae1e2b5

layoutd merged commit abfb15b into trunk Feb 4, 2026

layoutd deleted the exact-ratio-distribution branch February 4, 2026 12:44

Navigation Menu

Repository navigation

Add exact ratio distribution for deterministic test data generation - #186

Add exact ratio distribution for deterministic test data generation#186
layoutd merged 70 commits into
trunkfrom
exact-ratio-distribution

layoutd commented Oct 27, 2025 •

edited

Loading

Uh oh!

chihsuan left a comment

Uh oh!

layoutd commented Feb 4, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

layoutd commented Oct 27, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Current Behavior (Probabilistic)

New Behavior (Deterministic)

Key Changes

Benefits

Testing

Coupon Distribution

Refund Distribution

Uh oh!

chihsuan left a comment

Choose a reason for hiding this comment

Uh oh!

layoutd commented Feb 4, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

layoutd commented Oct 27, 2025 •

edited

Loading