@dereekb/firebase 13.31.0 → 13.33.0

package/test/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@dereekb/firebase/test",
-  "version": "13.31.0",
+  "version": "13.33.0",
   "peerDependencies": {
-    "@dereekb/date": "13.31.0",
-    "@dereekb/firebase": "13.31.0",
-    "@dereekb/model": "13.31.0",
-    "@dereekb/rxjs": "13.31.0",
-    "@dereekb/util": "13.31.0",
+    "@dereekb/date": "13.33.0",
+    "@dereekb/firebase": "13.33.0",
+    "@dereekb/model": "13.33.0",
+    "@dereekb/rxjs": "13.33.0",
+    "@dereekb/util": "13.33.0",
     "@firebase/rules-unit-testing": "5.0.0",
     "date-fns": "^4.1.0",
     "firebase": "^12.12.1",

package/test/src/lib/client/firebase.rules.d.ts

@@ -0,0 +1,114 @@
+import { type Maybe } from '@dereekb/util';
+import { type EmulatorConfig, type RulesTestEnvironment, type TokenOptions } from '@firebase/rules-unit-testing';
+import { type Firestore } from 'firebase/firestore';
+export { assertFails, assertSucceeds } from '@firebase/rules-unit-testing';
+/**
+ * Default file name of the workspace's Firestore security rules.
+ */
+export declare const DEFAULT_FIRESTORE_RULES_FILE_NAME = "firestore.rules";
+/**
+ * Configuration for {@link readFirestoreRulesFile}.
+ */
+export interface ReadFirestoreRulesFileConfig {
+    /**
+     * A path or `import.meta.url` to begin searching upward from.
+     *
+     * Resolve from the calling module rather than `process.cwd()`: vitest sets `root` to the project
+     * directory, so the working directory is not the workspace root when specs run.
+     */
+    readonly from: string;
+    /**
+     * File name to look for. Defaults to `firestore.rules`.
+     */
+    readonly fileName?: Maybe<string>;
+}
+/**
+ * Reads the workspace's Firestore rules file by walking up from the given module/path.
+ *
+ * @param config - The starting location and optional file name.
+ * @returns The contents of the rules file.
+ * @throws {Error} When no rules file is found at or above the starting location.
+ */
+export declare function readFirestoreRulesFile(config: ReadFirestoreRulesFileConfig): string;
+/**
+ * Configuration for {@link firestoreRulesTestBuilder}.
+ */
+export interface FirestoreRulesTestConfig {
+    /**
+     * Explicit project id for the rules test environment.
+     *
+     * Rules tests must not share a project id with other suites, since documents seeded with rules
+     * disabled would otherwise be visible across suites.
+     */
+    readonly projectId: string;
+    /**
+     * The Firestore security rules source to load. See {@link readFirestoreRulesFile}.
+     */
+    readonly rules: string;
+    /**
+     * Optional emulator connection details. Defaults to the emulator config in the environment.
+     */
+    readonly firestore?: Maybe<EmulatorConfig>;
+}
+/**
+ * Fixture handed to a {@link firestoreRulesTestBuilder} test body.
+ *
+ * Exposes RAW `firebase/firestore` handles rather than a `TestFirestoreContext`: the
+ * `firebaseRulesUnitTestBuilder()` drivers wrap every collection path with
+ * `makeTestingFirestoreAccesorDriver`, which fuzzes it to `${time}_${random}_${path}_${n}` — a
+ * fuzzed path can never match a `match /uec/{id}` rule, so those drivers cannot test rules.
+ */
+export interface FirestoreRulesTestFixture {
+    /**
+     * The underlying rules test environment.
+     */
+    readonly rulesTestEnvironment: RulesTestEnvironment;
+    /**
+     * Returns a Firestore handle authenticated as the given user.
+     *
+     * @param userId - The uid to authenticate as.
+     * @param tokenOptions - Optional additional auth token claims.
+     * @returns A Firestore instance subject to the loaded security rules.
+     */
+    firestoreForUser(userId: string, tokenOptions?: Maybe<TokenOptions>): Firestore;
+    /**
+     * Returns an unauthenticated Firestore handle.
+     *
+     * @returns A Firestore instance subject to the loaded security rules.
+     */
+    unauthenticatedFirestore(): Firestore;
+    /**
+     * Runs the given function with security rules disabled, for seeding documents.
+     *
+     * @param fn - Receives a rules-bypassing Firestore instance.
+     * @returns A promise that resolves when the seeding completes.
+     */
+    withSecurityRulesDisabled(fn: (firestore: Firestore) => Promise<void>): Promise<void>;
+}
+/**
+ * Registers vitest hooks that initialize a Firestore security-rules test environment, and invokes
+ * the given callback with a {@link FirestoreRulesTestFixture}.
+ *
+ * The environment is created once per suite (`beforeAll`), torn down once (`afterAll`), and the
+ * Firestore data is cleared between tests (`beforeEach`).
+ *
+ * @param config - The project id and rules to load.
+ * @returns A function that takes the test body builder.
+ *
+ * @example
+ * ```ts
+ * const rulesTest = firestoreRulesTestBuilder({
+ *   projectId: 'demo-api-rules-test',
+ *   rules: readFirestoreRulesFile({ from: import.meta.url })
+ * });
+ *
+ * describe('firestore.rules', () => {
+ *   rulesTest((f) => {
+ *     it('allows the owner to read their own document', async () => {
+ *       await assertSucceeds(getDoc(doc(f.firestoreForUser('a'), 'uec', 'a')));
+ *     });
+ *   });
+ * });
+ * ```
+ */
+export declare function firestoreRulesTestBuilder(config: FirestoreRulesTestConfig): (buildTests: (fixture: FirestoreRulesTestFixture) => void) => void;

package/test/src/lib/client/index.d.ts

@@ -1,3 +1,4 @@
 export * from './firebase.authorized';
 export * from './firestore.mock.item.fixture.authorized';
 export * from './firebase';
+export * from './firebase.rules';