@sureq/store-test 0.0.0-stage → 1.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +48 -2
- package/dist/index.cjs +8492 -0
- package/dist/index.cjs.map +1 -0
- package/dist/index.d.cts +96 -0
- package/dist/index.d.ts +96 -0
- package/dist/index.js +8468 -0
- package/dist/index.js.map +1 -0
- package/package.json +59 -4
package/dist/index.d.cts
ADDED
|
@@ -0,0 +1,96 @@
|
|
|
1
|
+
import { Scope, Store, StoreCapabilities } from "@sureq/core";
|
|
2
|
+
/** The store's clock under test: the suite moves it to expire leases and reach due times. */
|
|
3
|
+
interface TestClock {
|
|
4
|
+
/** The current fake time, in epoch ms. */
|
|
5
|
+
now(): number;
|
|
6
|
+
/** Move the clock forward by `ms`. */
|
|
7
|
+
advance(ms: number): void;
|
|
8
|
+
}
|
|
9
|
+
/** What `createStore` gets: the clock to use (`null` means the store's real clock) and a unique id. */
|
|
10
|
+
interface HarnessContext {
|
|
11
|
+
/** The clock the store must read; `null` means the store uses its real clock. */
|
|
12
|
+
clock: TestClock | null;
|
|
13
|
+
/** A unique id for this call, to keep stores of different tests apart. */
|
|
14
|
+
scopeId: string;
|
|
15
|
+
}
|
|
16
|
+
/** What `createStore` returns. `reopen` is required when the store declares `durable`. */
|
|
17
|
+
interface StoreHandle {
|
|
18
|
+
/** The store under test. */
|
|
19
|
+
store: Store;
|
|
20
|
+
/** A new store object over the same data, as after a restart. Required when the store declares `durable`. */
|
|
21
|
+
reopen?: () => Promise<Store>;
|
|
22
|
+
/** Drop what this store created. Called when the group ends. */
|
|
23
|
+
cleanup: () => Promise<void>;
|
|
24
|
+
}
|
|
25
|
+
/** The test runner functions the suite registers with. */
|
|
26
|
+
interface RunnerHooks {
|
|
27
|
+
/** Your runner's `describe`. */
|
|
28
|
+
describe: (name: string, fn: () => void) => void;
|
|
29
|
+
/** Your runner's `it` or `test`. */
|
|
30
|
+
it: (name: string, fn: () => Promise<void> | void) => void;
|
|
31
|
+
/** Your runner's `before` or `beforeAll`. */
|
|
32
|
+
before: (fn: () => Promise<void> | void) => void;
|
|
33
|
+
/** Your runner's `after` or `afterAll`. */
|
|
34
|
+
after: (fn: () => Promise<void> | void) => void;
|
|
35
|
+
}
|
|
36
|
+
/** Options for `runStoreConformance`. */
|
|
37
|
+
interface ConformanceOptions {
|
|
38
|
+
/** The store's name, written to the report. */
|
|
39
|
+
name: string;
|
|
40
|
+
/** Called once per group (and once per extra pod or fresh store a test asks for). */
|
|
41
|
+
createStore(ctx: HarnessContext): Promise<StoreHandle>;
|
|
42
|
+
/** Defaults to the detected node:test, Vitest or Jest globals. */
|
|
43
|
+
runner?: RunnerHooks;
|
|
44
|
+
/** Simulated pods in race tests (default 20; at least 10 to be conformant). */
|
|
45
|
+
concurrency?: number;
|
|
46
|
+
/** Repeats per race test (default 200). */
|
|
47
|
+
iterations?: number;
|
|
48
|
+
/** Multiplies every real wait (default 1). */
|
|
49
|
+
timeScale?: number;
|
|
50
|
+
/** Groups to skip; only `capabilities:<flag>` names keep the run conformant. */
|
|
51
|
+
skip?: string[];
|
|
52
|
+
/** Extra opt-in groups to run; a name that is not a group throws `InvalidOptionError`. */
|
|
53
|
+
groups?: string[];
|
|
54
|
+
/** Run every group on the store's real clock (for stores whose clock cannot be faked). */
|
|
55
|
+
realTime?: boolean;
|
|
56
|
+
/** Builds a core queue over the store in the given scope (its namespace and queue name), for tests that need core's own loops. */
|
|
57
|
+
core?: (store: Store, scope: Scope) => unknown;
|
|
58
|
+
/** Path of the JSON report to write. */
|
|
59
|
+
report?: string;
|
|
60
|
+
}
|
|
61
|
+
/** The JSON report written to the `report` path. */
|
|
62
|
+
interface ConformanceReport {
|
|
63
|
+
/** The suite version, `SUITE_VERSION`. */
|
|
64
|
+
suite: string;
|
|
65
|
+
/** The contract version of the `@sureq/core` the suite ran against, not the store's. */
|
|
66
|
+
contractVersion: number;
|
|
67
|
+
/** The `name` option. */
|
|
68
|
+
store: string;
|
|
69
|
+
/** The store's declared capabilities, or null when the run never read them. */
|
|
70
|
+
capabilities: StoreCapabilities | null;
|
|
71
|
+
/** Tests that passed. */
|
|
72
|
+
passed: number;
|
|
73
|
+
/** Tests that failed. */
|
|
74
|
+
failed: number;
|
|
75
|
+
/** Tests that were skipped. */
|
|
76
|
+
skipped: number;
|
|
77
|
+
/** Groups that did not run. */
|
|
78
|
+
skippedGroups: string[];
|
|
79
|
+
/** True only when nothing failed, no group other than a `capabilities:` gate was skipped, `concurrency` is at least 10, and the `clock` and `lease` groups ran in real time. */
|
|
80
|
+
conformant: boolean;
|
|
81
|
+
/** The clock mode of the run. */
|
|
82
|
+
mode: 'fake' | 'real';
|
|
83
|
+
/** The mode each part actually ran in. */
|
|
84
|
+
modes: {
|
|
85
|
+
clock: 'real' | 'fake';
|
|
86
|
+
lease: 'real' | 'fake';
|
|
87
|
+
rest: 'real' | 'fake';
|
|
88
|
+
};
|
|
89
|
+
/** Simulated pods in race tests. */
|
|
90
|
+
concurrency: number;
|
|
91
|
+
}
|
|
92
|
+
/** The conformance suite's own version, written to the report; it grows when tests are added. */
|
|
93
|
+
export declare const SUITE_VERSION: string;
|
|
94
|
+
/** Register the store conformance suite with the test runner; a contract violation is a test failure. */
|
|
95
|
+
export declare function runStoreConformance(options: ConformanceOptions): void;
|
|
96
|
+
export type { ConformanceOptions, ConformanceReport, HarnessContext, RunnerHooks, StoreHandle, TestClock };
|
package/dist/index.d.ts
ADDED
|
@@ -0,0 +1,96 @@
|
|
|
1
|
+
import { Scope, Store, StoreCapabilities } from "@sureq/core";
|
|
2
|
+
/** The store's clock under test: the suite moves it to expire leases and reach due times. */
|
|
3
|
+
interface TestClock {
|
|
4
|
+
/** The current fake time, in epoch ms. */
|
|
5
|
+
now(): number;
|
|
6
|
+
/** Move the clock forward by `ms`. */
|
|
7
|
+
advance(ms: number): void;
|
|
8
|
+
}
|
|
9
|
+
/** What `createStore` gets: the clock to use (`null` means the store's real clock) and a unique id. */
|
|
10
|
+
interface HarnessContext {
|
|
11
|
+
/** The clock the store must read; `null` means the store uses its real clock. */
|
|
12
|
+
clock: TestClock | null;
|
|
13
|
+
/** A unique id for this call, to keep stores of different tests apart. */
|
|
14
|
+
scopeId: string;
|
|
15
|
+
}
|
|
16
|
+
/** What `createStore` returns. `reopen` is required when the store declares `durable`. */
|
|
17
|
+
interface StoreHandle {
|
|
18
|
+
/** The store under test. */
|
|
19
|
+
store: Store;
|
|
20
|
+
/** A new store object over the same data, as after a restart. Required when the store declares `durable`. */
|
|
21
|
+
reopen?: () => Promise<Store>;
|
|
22
|
+
/** Drop what this store created. Called when the group ends. */
|
|
23
|
+
cleanup: () => Promise<void>;
|
|
24
|
+
}
|
|
25
|
+
/** The test runner functions the suite registers with. */
|
|
26
|
+
interface RunnerHooks {
|
|
27
|
+
/** Your runner's `describe`. */
|
|
28
|
+
describe: (name: string, fn: () => void) => void;
|
|
29
|
+
/** Your runner's `it` or `test`. */
|
|
30
|
+
it: (name: string, fn: () => Promise<void> | void) => void;
|
|
31
|
+
/** Your runner's `before` or `beforeAll`. */
|
|
32
|
+
before: (fn: () => Promise<void> | void) => void;
|
|
33
|
+
/** Your runner's `after` or `afterAll`. */
|
|
34
|
+
after: (fn: () => Promise<void> | void) => void;
|
|
35
|
+
}
|
|
36
|
+
/** Options for `runStoreConformance`. */
|
|
37
|
+
interface ConformanceOptions {
|
|
38
|
+
/** The store's name, written to the report. */
|
|
39
|
+
name: string;
|
|
40
|
+
/** Called once per group (and once per extra pod or fresh store a test asks for). */
|
|
41
|
+
createStore(ctx: HarnessContext): Promise<StoreHandle>;
|
|
42
|
+
/** Defaults to the detected node:test, Vitest or Jest globals. */
|
|
43
|
+
runner?: RunnerHooks;
|
|
44
|
+
/** Simulated pods in race tests (default 20; at least 10 to be conformant). */
|
|
45
|
+
concurrency?: number;
|
|
46
|
+
/** Repeats per race test (default 200). */
|
|
47
|
+
iterations?: number;
|
|
48
|
+
/** Multiplies every real wait (default 1). */
|
|
49
|
+
timeScale?: number;
|
|
50
|
+
/** Groups to skip; only `capabilities:<flag>` names keep the run conformant. */
|
|
51
|
+
skip?: string[];
|
|
52
|
+
/** Extra opt-in groups to run; a name that is not a group throws `InvalidOptionError`. */
|
|
53
|
+
groups?: string[];
|
|
54
|
+
/** Run every group on the store's real clock (for stores whose clock cannot be faked). */
|
|
55
|
+
realTime?: boolean;
|
|
56
|
+
/** Builds a core queue over the store in the given scope (its namespace and queue name), for tests that need core's own loops. */
|
|
57
|
+
core?: (store: Store, scope: Scope) => unknown;
|
|
58
|
+
/** Path of the JSON report to write. */
|
|
59
|
+
report?: string;
|
|
60
|
+
}
|
|
61
|
+
/** The JSON report written to the `report` path. */
|
|
62
|
+
interface ConformanceReport {
|
|
63
|
+
/** The suite version, `SUITE_VERSION`. */
|
|
64
|
+
suite: string;
|
|
65
|
+
/** The contract version of the `@sureq/core` the suite ran against, not the store's. */
|
|
66
|
+
contractVersion: number;
|
|
67
|
+
/** The `name` option. */
|
|
68
|
+
store: string;
|
|
69
|
+
/** The store's declared capabilities, or null when the run never read them. */
|
|
70
|
+
capabilities: StoreCapabilities | null;
|
|
71
|
+
/** Tests that passed. */
|
|
72
|
+
passed: number;
|
|
73
|
+
/** Tests that failed. */
|
|
74
|
+
failed: number;
|
|
75
|
+
/** Tests that were skipped. */
|
|
76
|
+
skipped: number;
|
|
77
|
+
/** Groups that did not run. */
|
|
78
|
+
skippedGroups: string[];
|
|
79
|
+
/** True only when nothing failed, no group other than a `capabilities:` gate was skipped, `concurrency` is at least 10, and the `clock` and `lease` groups ran in real time. */
|
|
80
|
+
conformant: boolean;
|
|
81
|
+
/** The clock mode of the run. */
|
|
82
|
+
mode: 'fake' | 'real';
|
|
83
|
+
/** The mode each part actually ran in. */
|
|
84
|
+
modes: {
|
|
85
|
+
clock: 'real' | 'fake';
|
|
86
|
+
lease: 'real' | 'fake';
|
|
87
|
+
rest: 'real' | 'fake';
|
|
88
|
+
};
|
|
89
|
+
/** Simulated pods in race tests. */
|
|
90
|
+
concurrency: number;
|
|
91
|
+
}
|
|
92
|
+
/** The conformance suite's own version, written to the report; it grows when tests are added. */
|
|
93
|
+
export declare const SUITE_VERSION: string;
|
|
94
|
+
/** Register the store conformance suite with the test runner; a contract violation is a test failure. */
|
|
95
|
+
export declare function runStoreConformance(options: ConformanceOptions): void;
|
|
96
|
+
export type { ConformanceOptions, ConformanceReport, HarnessContext, RunnerHooks, StoreHandle, TestClock };
|