@kovojs/test

function assertMutationError<
  const Key extends string,
  InputSchema extends Schema<unknown>,
  Errors extends Record<string, Schema<unknown>>,
  Request,
  Value,
  const Code extends Extract<keyof Errors, string>,
>(
  mutation: MutationDefinition<Key, InputSchema, Errors, Request, Value>,
  result: MutationResult<Value>,
  expected: MutationErrorExpectation<Errors, Code>,
): InferSchema<Errors[Code]>;

import { propertyTest } from '@kovojs/test/assertions';

type Cart = { count: number };

const result = propertyTest<Cart, { quantity: number }>({
  apply: (state, input) => ({ count: state.count + input.quantity }),
  predict: (state, input) => ({ count: state.count + input.quantity }),
  cases: [{ state: { count: 0 }, input: { quantity: 2 } }],
});
// result.cases === 1

function propertyTest<State, Input, ClientShape = State>(
  options: PropertyTestOptions<State, Input, ClientShape>,
): PropertyTestResult;

type MutationErrorExpectation<
  Errors extends Record<string, Schema<unknown>>,
  Code extends Extract<keyof Errors, string>,
> =
  | Code
  | {
      code: Code;
      payload?: InferSchema<Errors[Code]>;
    };

interface PropertyCase<State, Input> {
  input: Input;
  state: State;
}

interface PropertyTestOptions<State, Input, ClientShape = unknown> {
  apply: (state: State, input: Input) => State;
  cases: Iterable<PropertyCase<State, Input>>;
  predict: (state: State, input: Input) => ClientShape;
  shape?: (state: State) => ClientShape;
}

interface PropertyTestResult {
  cases: number;
}

function mutationCsrfTokenForTesting<Request>(
  request: Request,
  options: CsrfOptions<Request>,
  context: { mutation: string | { readonly key: string } },
): string;

function headerValues(source: Headers | HeaderRecord | undefined, name: string): string[];

function setCookieValues(source: Headers | HeaderRecord | undefined): string[];

function cookiePair(setCookie: string | undefined): string;

function firstSetCookiePair(source: Headers | HeaderRecord | undefined): string;

function decodeFrameworkIdentityToken(value: unknown): string | undefined;

function enhancedMutationHeaders(
  options: EnhancedMutationHeaderOptions = {},
): Record<string, string>;

type HeaderRecord = Record<string, string | string[] | undefined>;

interface EnhancedMutationTarget {
  queries?: readonly string[] | string;
  target: string;
}

interface EnhancedMutationLiveTarget {
  attestation: string;
  component: string;
  props?: Record<string, unknown>;
  target: string;
}

interface EnhancedMutationHeaderOptions {
  formTarget?: string;
  liveTargets?: readonly (EnhancedMutationLiveTarget | string)[] | string;
  targets?: readonly (EnhancedMutationTarget | string)[] | string;
}

async function createKovoTestHarness<App extends KovoApp>(
  app: App,
  options: KovoTestHarnessOptions<App>,
): Promise<KovoTestContext<App>>;

interface PageAssertion {
  /** Extract one named Kovo fragment from the full rendered response. */
  fragment(target: string): string;
  /** Full rendered response body. */
  html: string;
}

interface DbVerificationDiagnostic extends RegisteredDiagnostic<DiagnosticCode> {
  /** Static branch label when the diagnostic is branch-specific. */
  branch?: string;
  /** Declared or observed application data domain. */
  domain: string;
  /** Authored source site when retained by build evidence. */
  site?: string;
}

type KovoTestDb<App extends KovoApp> =
  InferKovoAppTypes<App> extends { readonly db: infer Db } ? Db : never;

type KovoTestRequest<App extends KovoApp> =
  InferKovoAppTypes<App> extends { readonly request: infer Request } ? Request : never;

type KovoTestRawRequest<App extends KovoApp> =
  InferKovoAppTypes<App> extends { readonly rawRequest: infer Request }
    ? Request
    : globalThis.Request;

type KovoTestMutation<App extends KovoApp> =
  InferKovoAppTypes<App> extends {
    readonly declarations: { readonly mutation: infer Mutation };
  }
    ? Mutation
    : never;

type KovoTestQuery<App extends KovoApp> =
  InferKovoAppTypes<App> extends {
    readonly declarations: { readonly query: infer Query };
  }
    ? Query
    : never;

type KovoTestRouteKey<App extends KovoApp> =
  InferKovoAppTypes<App> extends {
    readonly declarations: { readonly route: infer Route };
  }
    ? Route extends RouteHandle<infer Path, infer _Owner>
      ? Path
      : never
    : never;

type KovoTestMutationInput<Mutation> =
  Mutation extends MutationHandle<infer Input, infer _Value, infer _Errors, infer _Owner>
    ? Input
    : never;

type KovoTestMutationValue<Mutation> =
  Mutation extends MutationHandle<infer _Input, infer Value, infer _Errors, infer _Owner>
    ? Value
    : never;

type KovoTestMutationError<Mutation> =
  Mutation extends MutationHandle<infer _Input, infer _Value, infer Errors, infer _Owner>
    ? {
        [Code in Extract<keyof Errors, string>]: MutationFail<Code, InferSchema<Errors[Code]>>;
      }[Extract<keyof Errors, string>]
    : never;

type KovoTestFrameworkMutationError =
  | MutationFail<'CSRF', Record<never, never>>
  | MutationFail<'RATE_LIMITED', unknown>
  | MutationFail<'STALE_VERSION', Record<never, never>>
  | MutationFail<'UNAUTHORIZED', unknown>
  | MutationFail<'VALIDATION', ValidationFailurePayload>;

type KovoTestMutationResult<Mutation> =
  | KovoTestFrameworkMutationError
  | KovoTestMutationError<Mutation>
  | MutationSuccess<KovoTestMutationValue<Mutation>, KovoTestMutationInput<Mutation>>;

type KovoTestQueryInput<Query> =
  Query extends QueryHandle<infer Input, infer _Value, infer _Owner> ? Input : never;

type KovoTestQueryResult<Query> =
  Query extends QueryHandle<infer _Input, infer Value, infer _Owner> ? Awaited<Value> : never;

interface KovoTestVerificationConfig {
  domainByTable: Record<string, string>;
  exemptTables?: readonly string[];
  keyByTable?: Record<string, string>;
  sqlDialect?: 'postgres' | 'sqlite';
}

interface KovoTestHarnessOptions<App extends KovoApp> {
  /**
   * Exact successful-build graph to consume. Relative paths are rejected so tests cannot
   * accidentally trust a nearby artifact (SPEC §§5.2.4 and 12).
   */
  artifact: string | URL;
  /** Absolute project root used to re-hash every analyzed source/config input. */
  projectRoot: string | URL;
  /**
   * Explicit origin of a separately bootstrapped app used by `page()` and `request()`.
   * Direct `query()` and `exec()` tests do not require it.
   */
  baseUrl?: string | URL;
  /** Optional test DB whose type is inferred from the imported app contract. */
  db?: KovoTestDb<App>;
  /** Typed provider/request fixture merged into direct query and mutation execution. */
  request?: Partial<Omit<KovoTestRequest<App>, 'db'>>;
  /**
   * Runtime adapter mapping used by SQL observation. Touch/read facts cannot be supplied here;
   * those come only from the verified build graph.
   */
  verification?: KovoTestVerificationConfig;
}

interface KovoTestExecOptions<App extends KovoApp> {
  csrf?: CsrfOptions<KovoTestRequest<App>>;
  request?: Partial<Omit<KovoTestRequest<App>, 'db'>>;
}

interface KovoTestContext<App extends KovoApp> {
  readonly db: KovoTestDb<App> | undefined;
  exec<Mutation extends KovoTestMutation<App>>(
    mutation: Mutation,
    input: KovoTestMutationInput<Mutation>,
    options?: KovoTestExecOptions<App>,
  ): Promise<KovoTestMutationResult<Mutation>>;
  page(path: KovoTestRouteKey<App>, init?: Omit<RequestInit, 'method'>): Promise<PageAssertion>;
  query<Query extends KovoTestQuery<App>>(
    query: Query,
    ...input: [KovoTestQueryInput<Query>] extends [undefined]
      ? [input?: undefined]
      : [input: KovoTestQueryInput<Query>]
  ): Promise<KovoTestQueryResult<Query>>;
  request(request: KovoTestRawRequest<App>): Promise<Response>;
  verificationDiagnostics(): readonly DbVerificationDiagnostic[];
}

function fragmentHtml(html: string, target: string): string;

function htmlElementCount(html: string, selector: HtmlElementSelector = {}): number;

function htmlElementFacts(
  html: string,
  selector: HtmlElementSelector = {},
): HtmlElementFact[];

function htmlDocumentFacts(html: string): HtmlDocumentFact;

function htmlLinkHrefs(html: string, attrs: Record<string, string | true> = {}): string[];

function kovoQueryJsonValues(html: string, name: string): unknown[];

function htmlFormFacts(html: string): HtmlFormFact[];

function htmlFormActions(html: string): string[];

function htmlFormFields(html: string, name?: string): HtmlFormFieldFact[];

function htmlFormFieldsByName(
  form: HtmlFormFact | undefined,
): Record<string, HtmlFormFieldFact>;

function htmlKeyFacts(html: string, key?: string): HtmlKeyFact[];

function htmlKeyValues(html: string): string[];

function htmlKeyTextMap(html: string): Record<string, string>;

function htmlTextContent(html: string): string;

interface HtmlElementFact {
  attrs: Record<string, string>;
  html: string;
  innerHtml: string;
  tag: string;
}

interface HtmlElementSelector {
  attrs?: Record<string, string | true>;
  tag?: string;
}

interface HtmlJsonScriptFact {
  attrs: Record<string, string>;
  html: string;
  json: unknown;
  rawJson: string;
}

interface HtmlDocumentFact {
  bodyAttrs: Record<string, string>;
  jsonScripts: HtmlJsonScriptFact[];
  links: HtmlElementFact[];
  metas: HtmlElementFact[];
  text: string;
  title: string;
}

interface HtmlFormFieldFact {
  attrs: Record<string, string>;
  html: string;
  name: string;
  tag: string;
  type: string;
  value: string;
}

interface HtmlFormFact {
  action: string;
  attrs: Record<string, string>;
  fields: HtmlFormFieldFact[];
  html: string;
  innerHtml: string;
  method: string;
}

interface HtmlKeyFact {
  attrs: Record<string, string>;
  html: string;
  innerHtml: string;
  key: string;
  tag: string;
  text: string;
}

async function createPgliteTestDb(options: PGliteOptions = {}): Promise<PgliteTestDb>;

interface PgliteStatementCarrier {
  /** Drizzle SQL chunks, used by Kovo static/parameterized SQL objects. */
  queryChunks?: readonly unknown[];
  /** SQL text, matching common driver carrier shape. */
  sql?: string;
  /** SQL text, matching common driver carrier shape. */
  text?: string;
  /** Bound statement values. */
  values?: readonly unknown[];
}

type PgliteStatementInput = string | PgliteStatementCarrier;

interface PgliteTestDb {
  close(): Promise<void>;
  exec(statement: PgliteStatementInput): Promise<Results[]>;
  pglite: PGlite;
  query<Row extends Record<string, unknown> = Record<string, unknown>>(
    statement: PgliteStatementInput,
    params?: readonly unknown[],
  ): Promise<Row[]>;
  read<Row extends Record<string, unknown> = Record<string, unknown>>(
    table: string,
  ): Promise<Row[]>;
  write(table: string, value: Record<string, unknown>): Promise<void>;
}

async function createPostgresTestRuntime(
  options: KovoPostgresTestRuntimeOptions,
): Promise<KovoPostgresTestRuntime>;

type KovoPostgresTestDb = KovoPostgresRuntimeDb;

type KovoPostgresTestAdminDb = Pick<
  KovoPostgresRuntimeDb,
  Extract<keyof KovoPostgresRuntimeDb, '$count' | '$with' | 'query' | 'select' | 'selectDistinct'>
> & {
  crossOwnerRead<Row = unknown>(
    statement: unknown,
    declaration: CrossOwnerReadDeclaration,
  ): Promise<Row[]> | Row[];
  rawRead<Row = unknown>(
    statement: unknown,
    declaration: RawReadDeclaration,
  ): Promise<Row[]> | Row[];
};

type KovoPostgresTestSystemDb = KovoPostgresRuntimeDb;

interface KovoPostgresTestRuntimeOptions {
  /**
   * Physical owner/authz tables allowed through the audited admin cross-owner read path.
   * Each test must opt in per table (SPEC §10.3 DEC-G).
   */
  crossOwnerReadTables?: readonly string[];
  /** App schema module, normally `import * as schema from '../src/schema.js'`. */
  schema: Record<string, unknown>;
  /** SQL run after the ephemeral PGlite schema is provisioned. */
  seedSql?: string | readonly string[];
}

interface KovoPostgresTestRuntime {
  /** Temporary data directory removed by {@link close}. */
  readonly dataDir: string;
  /** Release the runtime and remove its temporary data. */
  close(): Promise<void>;
  /** Run with one owner principal through Kovo's request-scoped database capability. */
  withPrincipal<Result>(
    principalId: string,
    callback: (db: KovoPostgresTestDb) => Result | Promise<Result>,
  ): Promise<Result>;
  /** Run an explicitly table-scoped, admin-guarded cross-owner read. */
  asAdmin<Result>(
    principalId: string,
    callback: (db: KovoPostgresTestAdminDb) => Result | Promise<Result>,
  ): Promise<Result>;
  /** Run audited non-request system work with a required non-empty reason. */
  asSystem<Result>(
    reason: string,
    callback: (db: KovoPostgresTestSystemDb) => Result | Promise<Result>,
  ): Promise<Result>;
}

function createSqliteTestDb(options: SqliteTestDbOptions = {}): SqliteTestDb;

interface SqliteStatementCarrier {
  /** SQL text, matching common driver carrier shape. */
  sql?: string;
  /** SQL text, matching common driver carrier shape. */
  text?: string;
  /** Bound statement values. */
  values?: readonly unknown[];
}

type SqliteStatementInput = string | SqliteStatementCarrier;

interface SqliteNativeStatement<Row = unknown> {
  all(...params: unknown[]): Row[];
  run(...params: unknown[]): unknown;
}

interface SqliteNativeHandle {
  close(): void;
  exec(statement: string): unknown;
  prepare<Row = unknown>(statement: string): SqliteNativeStatement<Row>;
  transaction<Callback extends (...args: never[]) => unknown>(callback: Callback): Callback;
}

interface SqliteTestDbOptions {
  /** Database filename. Defaults to ':memory:'. Use a real file to enable a dedicated read-only reader connection. */
  filename?: string;
  /** Require the database file to already exist before opening it. */
  fileMustExist?: boolean;
  /** Path to a custom better-sqlite3 native binding. */
  nativeBinding?: string;
  /** Open the database in read-only mode. */
  readonly?: boolean;
  /** Busy timeout in milliseconds. */
  timeout?: number;
  /** Optional SQL statement logger. */
  verbose?: (message?: unknown, ...additionalArgs: unknown[]) => void;
}

interface SqliteTestDb {
  close(): void;
  exec(statement: SqliteStatementInput): void;
  query<Row extends Record<string, unknown> = Record<string, unknown>>(
    statement: SqliteStatementInput,
    params?: readonly unknown[],
  ): Row[];
  read<Row extends Record<string, unknown> = Record<string, unknown>>(table: string): Row[];
  sqlite: SqliteNativeHandle;
  write(table: string, value: Record<string, unknown>): void;
}