/**
 * Picks one row out of a collection, failing loudly when it is not there.
 *
 * The pattern this replaces is `collection.find(...)` dereferenced straight
 * away — `customers.find(c => c.email === x).id`. When the row is missing the
 * test dies with "Cannot read properties of undefined" pointing at a line of
 * test plumbing, which says nothing about what was expected. The suite runs
 * fullyParallel against one shared database, so a lookup over a collection
 * other specs also write to can miss for reasons that have nothing to do with
 * the behaviour under test (#241).
 *
 * Deliberately imports nothing. It lives apart from `api.ts` so the Vitest
 * unit suite can cover it without pulling `@playwright/test` — and therefore a
 * browser harness — into a run configured for `environment: 'node'`.
 *
 * Throws rather than returning null: every caller wants the row, and an
 * Error at the point of the miss beats a null threaded through three more
 * lines before something else fails.
 */
export function findOrFail<T>(
  items: T[],
  predicate: (item: T) => boolean,
  description: string
): T {
  const found = items.find(predicate);

  if (found === undefined) {
    // The count matters as much as the description: "0 rows" means the
    // fixture never landed, while "37 rows" means it landed and the predicate
    // is wrong. Those are different bugs and the message should tell them
    // apart without a re-run.
    throw new Error(
      `expected to find ${description}, but none of the ${items.length} rows matched`
    );
  }

  return found;
}