@burojs/test-helpers 0.2.0

package/dist/index.d.cts

@@ -0,0 +1,201 @@
+import { ErasedQueryDescriptor, ErasedMutationDescriptor, BatchedQueryOperation, DataProvider } from '@burojs/core';
+
+/**
+ * Subset of Playwright's Page API that we depend on.
+ * Real consumers pass a real Page; tests pass a mock.
+ */
+interface PlaywrightLocator {
+    click: () => Promise<void>;
+    fill: (value: string) => Promise<void>;
+    textContent: () => Promise<string | null>;
+    getByTestId: (id: string) => PlaywrightLocator;
+    getByRole: (role: string, opts?: {
+        name?: string | RegExp;
+    }) => PlaywrightLocator;
+    isVisible: () => Promise<boolean>;
+}
+interface PlaywrightPage {
+    goto: (url: string) => Promise<unknown>;
+    getByTestId: (id: string) => PlaywrightLocator;
+    getByRole: (role: string, opts?: {
+        name?: string | RegExp;
+    }) => PlaywrightLocator;
+    url: () => string;
+}
+
+interface FormFieldObject {
+    input: () => PlaywrightLocator;
+    error: () => PlaywrightLocator;
+    help: () => PlaywrightLocator;
+}
+interface FormView {
+    field: (fieldName: string) => FormFieldObject;
+    section: (sectionKey: string) => PlaywrightLocator;
+    submit: () => PlaywrightLocator;
+    cancel: () => PlaywrightLocator;
+    action: (actionName: string) => PlaywrightLocator;
+}
+declare function createFormView(page: PlaywrightPage, resource: string, view: 'create' | 'edit' | 'show'): FormView;
+
+/**
+ * A row's address inside the filter-builder draft: `[]` is the root group,
+ * `[0]` is its first row, `[1, 0]` is the first row of the group nested at
+ * top-level index 1. Mirrors `DraftPath` in
+ * `packages/ui-shadcn/src/list-kit/filter-builder/draft.ts` — the testid
+ * suffix is `path.join('-')` (an empty path renders as the empty string, so
+ * the root group's own testid carries a trailing `:`, e.g.
+ * `list-filter:<r>:group::add-row`).
+ */
+type FilterRowPath = readonly number[];
+interface ListView {
+    goto: () => Promise<void>;
+    row: (recordId: string) => RowObject;
+    search: () => PlaywrightLocator;
+    /** The filter region container — `list-filters:<resource>`. */
+    filtersContainer: () => PlaywrightLocator;
+    /** Opens/closes the filter-builder popover. */
+    filterButton: () => PlaywrightLocator;
+    /** The popover body once open. */
+    filterPanel: () => PlaywrightLocator;
+    /** "+ Filter" — appends a new predicate row to the group at `groupPath` (root: `[]`). */
+    filterAddRow: (groupPath?: FilterRowPath) => PlaywrightLocator;
+    /** Field-select trigger for the row at `path`. */
+    filterRowField: (path: FilterRowPath) => PlaywrightLocator;
+    /** One field option inside an open field-select. */
+    filterRowFieldOption: (path: FilterRowPath, field: string) => PlaywrightLocator;
+    /** Operator-select trigger for the row at `path`. */
+    filterRowOp: (path: FilterRowPath) => PlaywrightLocator;
+    /** One operator option inside an open operator-select. */
+    filterRowOpOption: (path: FilterRowPath, op: string) => PlaywrightLocator;
+    /** Value control trigger/input for the row at `path` — shape depends on the field kind (text box, enum/relation/boolean popover). */
+    filterRowValue: (path: FilterRowPath) => PlaywrightLocator;
+    /** Removes the row at `path` from the draft (inside the panel, before Apply). */
+    filterRowRemove: (path: FilterRowPath) => PlaywrightLocator;
+    /** Commits the draft — applies it and closes the panel. */
+    filterApply: () => PlaywrightLocator;
+    /** Clears the draft back to empty (still requires Apply to take effect). */
+    filterReset: () => PlaywrightLocator;
+    /** One applied-filter badge outside the panel, by its top-level index. */
+    filterBadge: (index: number) => PlaywrightLocator;
+    /** A badge's × — removes that row immediately, no Apply needed. */
+    filterBadgeRemove: (index: number) => PlaywrightLocator;
+    /** "Clear all" — empties both the pinned slot and the builder group. */
+    filterClearAll: () => PlaywrightLocator;
+    /** An always-visible pinned control (`views.list.filters.pinned`) for `field`, rendered outside the panel. */
+    filterPinned: (field: string) => PlaywrightLocator;
+    paginationPrev: () => PlaywrightLocator;
+    paginationNext: () => PlaywrightLocator;
+    empty: () => PlaywrightLocator;
+    toolbar: () => PlaywrightLocator;
+    table: () => PlaywrightLocator;
+}
+interface RowObject {
+    cell: (fieldName: string) => PlaywrightLocator;
+    action: (actionName: string) => PlaywrightLocator;
+    checkbox: () => PlaywrightLocator;
+    open: () => Promise<void>;
+}
+interface ListViewOptions {
+    basePath?: string;
+}
+declare function createListView(page: PlaywrightPage, resource: string, options?: ListViewOptions): ListView;
+
+interface PickerObject {
+    dialog: () => PlaywrightLocator;
+    popover: () => PlaywrightLocator;
+    option: (value: string) => PlaywrightLocator;
+    search: () => PlaywrightLocator;
+    clear: () => PlaywrightLocator;
+    quickCreate: () => PlaywrightLocator;
+}
+declare function createPickerObject(page: PlaywrightPage, targetResource: string): PickerObject;
+
+type ShowView = FormView;
+declare function createShowView(page: PlaywrightPage, resource: string): ShowView;
+
+interface ResourceObject {
+    name: string;
+    list: (options?: ListViewOptions) => ListView;
+    edit: (recordId: string) => FormView;
+    show: (recordId: string) => ShowView;
+    create: () => FormView;
+    picker: () => PickerObject;
+}
+declare function createResourceObject(page: PlaywrightPage, name: string): ResourceObject;
+
+interface BuroPage {
+    resource: (name: string) => ResourceObject;
+    contextPicker: (sliceName: string) => PlaywrightLocator;
+    notification: (type: 'success' | 'error' | 'progress' | 'info') => PlaywrightLocator;
+    actionConfirm: (resource: string, scope: string, actionName: string) => PlaywrightLocator;
+    page: PlaywrightPage;
+}
+declare function createBuroPage(page: PlaywrightPage): BuroPage;
+
+interface ConfirmDialogObject {
+    dialog: () => PlaywrightLocator;
+    yes: () => PlaywrightLocator;
+    no: () => PlaywrightLocator;
+}
+declare function createConfirmDialog(page: PlaywrightPage, resource: string, scope: string, actionName: string): ConfirmDialogObject;
+
+type QueryKind = ErasedQueryDescriptor['kind'];
+type MutationKind = ErasedMutationDescriptor['kind'];
+interface ProviderObservedCall {
+    readonly lifecycle: 'query' | 'mutation' | 'batch' | 'live-open' | 'live-subscribe';
+    readonly kind?: QueryKind | MutationKind;
+    readonly descriptor?: ErasedQueryDescriptor | ErasedMutationDescriptor;
+    readonly descriptors?: readonly ErasedQueryDescriptor[];
+    readonly signal?: AbortSignal;
+}
+/** Specimens supplied by an adapter author; unsupported optional methods are omitted. */
+interface ProviderContractDescriptors {
+    readonly queries?: Partial<Record<QueryKind, ErasedQueryDescriptor>>;
+    readonly mutations?: Partial<Record<MutationKind, ErasedMutationDescriptor>>;
+    readonly batch?: readonly BatchedQueryOperation[];
+    /** Independent batch groups prove that grouping is explicit, never merged by the helper. */
+    readonly batchGroups?: readonly (readonly BatchedQueryOperation[])[];
+    /** List specimens for both pagination protocols, including expected totals/pageInfo. */
+    readonly pagination?: {
+        readonly offset?: ErasedQueryDescriptor;
+        readonly cursor?: ErasedQueryDescriptor;
+    };
+    readonly live?: ErasedQueryDescriptor;
+    /** Error specimens must make the selected handler reject with a DataError. */
+    readonly errors?: readonly ProviderContractErrorSpecimen[];
+    /** Hand-authored mapped results; assertions never derive expectations from an adapter. */
+    readonly expected?: {
+        readonly queries?: Partial<Record<QueryKind, unknown>>;
+        readonly mutations?: Partial<Record<MutationKind, unknown>>;
+        readonly batch?: unknown;
+        readonly pagination?: {
+            readonly offset?: unknown;
+            readonly cursor?: unknown;
+        };
+    };
+}
+type ProviderContractErrorSpecimen = {
+    readonly lifecycle: 'query';
+    readonly kind: QueryKind;
+    readonly descriptor: ErasedQueryDescriptor;
+} | {
+    readonly lifecycle: 'mutation';
+    readonly kind: MutationKind;
+    readonly descriptor: ErasedMutationDescriptor;
+};
+interface ProviderContractFixture {
+    create(): DataProvider | Promise<DataProvider>;
+    descriptors: ProviderContractDescriptors;
+    observeCalls(): readonly ProviderObservedCall[];
+}
+/**
+ * Registers transport-agnostic provider conformance tests. It intentionally
+ * imports only core contracts: adapters supply their own deterministic client
+ * and expose provider-boundary observations through the fixture.
+ */
+declare function dataProviderContract(name: string, fixture: ProviderContractFixture): void;
+
+declare const PACKAGE_NAME: "@burojs/test-helpers";
+declare const PACKAGE_VERSION: "0.0.0";
+
+export { type BuroPage, type ConfirmDialogObject, type FormFieldObject, type FormView, type ListView, type ListViewOptions, PACKAGE_NAME, PACKAGE_VERSION, type PickerObject, type PlaywrightLocator, type PlaywrightPage, type ProviderContractDescriptors, type ProviderContractFixture, type ProviderObservedCall, type ResourceObject, type RowObject, type ShowView, createBuroPage, createConfirmDialog, createFormView, createListView, createPickerObject, createResourceObject, createShowView, dataProviderContract };

package/dist/index.d.ts

@@ -0,0 +1,201 @@
+import { ErasedQueryDescriptor, ErasedMutationDescriptor, BatchedQueryOperation, DataProvider } from '@burojs/core';
+
+/**
+ * Subset of Playwright's Page API that we depend on.
+ * Real consumers pass a real Page; tests pass a mock.
+ */
+interface PlaywrightLocator {
+    click: () => Promise<void>;
+    fill: (value: string) => Promise<void>;
+    textContent: () => Promise<string | null>;
+    getByTestId: (id: string) => PlaywrightLocator;
+    getByRole: (role: string, opts?: {
+        name?: string | RegExp;
+    }) => PlaywrightLocator;
+    isVisible: () => Promise<boolean>;
+}
+interface PlaywrightPage {
+    goto: (url: string) => Promise<unknown>;
+    getByTestId: (id: string) => PlaywrightLocator;
+    getByRole: (role: string, opts?: {
+        name?: string | RegExp;
+    }) => PlaywrightLocator;
+    url: () => string;
+}
+
+interface FormFieldObject {
+    input: () => PlaywrightLocator;
+    error: () => PlaywrightLocator;
+    help: () => PlaywrightLocator;
+}
+interface FormView {
+    field: (fieldName: string) => FormFieldObject;
+    section: (sectionKey: string) => PlaywrightLocator;
+    submit: () => PlaywrightLocator;
+    cancel: () => PlaywrightLocator;
+    action: (actionName: string) => PlaywrightLocator;
+}
+declare function createFormView(page: PlaywrightPage, resource: string, view: 'create' | 'edit' | 'show'): FormView;
+
+/**
+ * A row's address inside the filter-builder draft: `[]` is the root group,
+ * `[0]` is its first row, `[1, 0]` is the first row of the group nested at
+ * top-level index 1. Mirrors `DraftPath` in
+ * `packages/ui-shadcn/src/list-kit/filter-builder/draft.ts` — the testid
+ * suffix is `path.join('-')` (an empty path renders as the empty string, so
+ * the root group's own testid carries a trailing `:`, e.g.
+ * `list-filter:<r>:group::add-row`).
+ */
+type FilterRowPath = readonly number[];
+interface ListView {
+    goto: () => Promise<void>;
+    row: (recordId: string) => RowObject;
+    search: () => PlaywrightLocator;
+    /** The filter region container — `list-filters:<resource>`. */
+    filtersContainer: () => PlaywrightLocator;
+    /** Opens/closes the filter-builder popover. */
+    filterButton: () => PlaywrightLocator;
+    /** The popover body once open. */
+    filterPanel: () => PlaywrightLocator;
+    /** "+ Filter" — appends a new predicate row to the group at `groupPath` (root: `[]`). */
+    filterAddRow: (groupPath?: FilterRowPath) => PlaywrightLocator;
+    /** Field-select trigger for the row at `path`. */
+    filterRowField: (path: FilterRowPath) => PlaywrightLocator;
+    /** One field option inside an open field-select. */
+    filterRowFieldOption: (path: FilterRowPath, field: string) => PlaywrightLocator;
+    /** Operator-select trigger for the row at `path`. */
+    filterRowOp: (path: FilterRowPath) => PlaywrightLocator;
+    /** One operator option inside an open operator-select. */
+    filterRowOpOption: (path: FilterRowPath, op: string) => PlaywrightLocator;
+    /** Value control trigger/input for the row at `path` — shape depends on the field kind (text box, enum/relation/boolean popover). */
+    filterRowValue: (path: FilterRowPath) => PlaywrightLocator;
+    /** Removes the row at `path` from the draft (inside the panel, before Apply). */
+    filterRowRemove: (path: FilterRowPath) => PlaywrightLocator;
+    /** Commits the draft — applies it and closes the panel. */
+    filterApply: () => PlaywrightLocator;
+    /** Clears the draft back to empty (still requires Apply to take effect). */
+    filterReset: () => PlaywrightLocator;
+    /** One applied-filter badge outside the panel, by its top-level index. */
+    filterBadge: (index: number) => PlaywrightLocator;
+    /** A badge's × — removes that row immediately, no Apply needed. */
+    filterBadgeRemove: (index: number) => PlaywrightLocator;
+    /** "Clear all" — empties both the pinned slot and the builder group. */
+    filterClearAll: () => PlaywrightLocator;
+    /** An always-visible pinned control (`views.list.filters.pinned`) for `field`, rendered outside the panel. */
+    filterPinned: (field: string) => PlaywrightLocator;
+    paginationPrev: () => PlaywrightLocator;
+    paginationNext: () => PlaywrightLocator;
+    empty: () => PlaywrightLocator;
+    toolbar: () => PlaywrightLocator;
+    table: () => PlaywrightLocator;
+}
+interface RowObject {
+    cell: (fieldName: string) => PlaywrightLocator;
+    action: (actionName: string) => PlaywrightLocator;
+    checkbox: () => PlaywrightLocator;
+    open: () => Promise<void>;
+}
+interface ListViewOptions {
+    basePath?: string;
+}
+declare function createListView(page: PlaywrightPage, resource: string, options?: ListViewOptions): ListView;
+
+interface PickerObject {
+    dialog: () => PlaywrightLocator;
+    popover: () => PlaywrightLocator;
+    option: (value: string) => PlaywrightLocator;
+    search: () => PlaywrightLocator;
+    clear: () => PlaywrightLocator;
+    quickCreate: () => PlaywrightLocator;
+}
+declare function createPickerObject(page: PlaywrightPage, targetResource: string): PickerObject;
+
+type ShowView = FormView;
+declare function createShowView(page: PlaywrightPage, resource: string): ShowView;
+
+interface ResourceObject {
+    name: string;
+    list: (options?: ListViewOptions) => ListView;
+    edit: (recordId: string) => FormView;
+    show: (recordId: string) => ShowView;
+    create: () => FormView;
+    picker: () => PickerObject;
+}
+declare function createResourceObject(page: PlaywrightPage, name: string): ResourceObject;
+
+interface BuroPage {
+    resource: (name: string) => ResourceObject;
+    contextPicker: (sliceName: string) => PlaywrightLocator;
+    notification: (type: 'success' | 'error' | 'progress' | 'info') => PlaywrightLocator;
+    actionConfirm: (resource: string, scope: string, actionName: string) => PlaywrightLocator;
+    page: PlaywrightPage;
+}
+declare function createBuroPage(page: PlaywrightPage): BuroPage;
+
+interface ConfirmDialogObject {
+    dialog: () => PlaywrightLocator;
+    yes: () => PlaywrightLocator;
+    no: () => PlaywrightLocator;
+}
+declare function createConfirmDialog(page: PlaywrightPage, resource: string, scope: string, actionName: string): ConfirmDialogObject;
+
+type QueryKind = ErasedQueryDescriptor['kind'];
+type MutationKind = ErasedMutationDescriptor['kind'];
+interface ProviderObservedCall {
+    readonly lifecycle: 'query' | 'mutation' | 'batch' | 'live-open' | 'live-subscribe';
+    readonly kind?: QueryKind | MutationKind;
+    readonly descriptor?: ErasedQueryDescriptor | ErasedMutationDescriptor;
+    readonly descriptors?: readonly ErasedQueryDescriptor[];
+    readonly signal?: AbortSignal;
+}
+/** Specimens supplied by an adapter author; unsupported optional methods are omitted. */
+interface ProviderContractDescriptors {
+    readonly queries?: Partial<Record<QueryKind, ErasedQueryDescriptor>>;
+    readonly mutations?: Partial<Record<MutationKind, ErasedMutationDescriptor>>;
+    readonly batch?: readonly BatchedQueryOperation[];
+    /** Independent batch groups prove that grouping is explicit, never merged by the helper. */
+    readonly batchGroups?: readonly (readonly BatchedQueryOperation[])[];
+    /** List specimens for both pagination protocols, including expected totals/pageInfo. */
+    readonly pagination?: {
+        readonly offset?: ErasedQueryDescriptor;
+        readonly cursor?: ErasedQueryDescriptor;
+    };
+    readonly live?: ErasedQueryDescriptor;
+    /** Error specimens must make the selected handler reject with a DataError. */
+    readonly errors?: readonly ProviderContractErrorSpecimen[];
+    /** Hand-authored mapped results; assertions never derive expectations from an adapter. */
+    readonly expected?: {
+        readonly queries?: Partial<Record<QueryKind, unknown>>;
+        readonly mutations?: Partial<Record<MutationKind, unknown>>;
+        readonly batch?: unknown;
+        readonly pagination?: {
+            readonly offset?: unknown;
+            readonly cursor?: unknown;
+        };
+    };
+}
+type ProviderContractErrorSpecimen = {
+    readonly lifecycle: 'query';
+    readonly kind: QueryKind;
+    readonly descriptor: ErasedQueryDescriptor;
+} | {
+    readonly lifecycle: 'mutation';
+    readonly kind: MutationKind;
+    readonly descriptor: ErasedMutationDescriptor;
+};
+interface ProviderContractFixture {
+    create(): DataProvider | Promise<DataProvider>;
+    descriptors: ProviderContractDescriptors;
+    observeCalls(): readonly ProviderObservedCall[];
+}
+/**
+ * Registers transport-agnostic provider conformance tests. It intentionally
+ * imports only core contracts: adapters supply their own deterministic client
+ * and expose provider-boundary observations through the fixture.
+ */
+declare function dataProviderContract(name: string, fixture: ProviderContractFixture): void;
+
+declare const PACKAGE_NAME: "@burojs/test-helpers";
+declare const PACKAGE_VERSION: "0.0.0";
+
+export { type BuroPage, type ConfirmDialogObject, type FormFieldObject, type FormView, type ListView, type ListViewOptions, PACKAGE_NAME, PACKAGE_VERSION, type PickerObject, type PlaywrightLocator, type PlaywrightPage, type ProviderContractDescriptors, type ProviderContractFixture, type ProviderObservedCall, type ResourceObject, type RowObject, type ShowView, createBuroPage, createConfirmDialog, createFormView, createListView, createPickerObject, createResourceObject, createShowView, dataProviderContract };