Deprecate withSubject() in favor of type-specific methods

Signed-off-by: Eric Peterson <ericpeterson@spotify.com>

.changeset/search-tofu-panaeng.md

@@ -0,0 +1,5 @@
+---
+'@backstage/plugin-search-backend-node': patch
+---
+
+Use of `TestPipeline.withSubject()` is now deprecated. Instead, use the `fromCollator`, `fromDecorator`, or `fromIndexer` static methods to instantiate a test pipeline. You may also use the class' `withCollator`, `withDecorator`, and `withIndexer` instance methods to build test pipelines that consist of multiple test subjects.

plugins/search-backend-node/api-report.md

@@ -173,7 +173,14 @@ export type ScheduleTaskParameters = {
 // @public
 export class TestPipeline {
   execute(): Promise<TestPipelineResult>;
+  static fromCollator(collator: Readable): TestPipeline;
+  static fromDecorator(decorator: Transform): TestPipeline;
+  static fromIndexer(indexer: Writable): TestPipeline;
+  withCollator(collator: Readable): this;
+  withDecorator(decorator: Transform): this;
   withDocuments(documents: IndexableDocument[]): TestPipeline;
+  withIndexer(indexer: Writable): this;
+  // @deprecated
   static withSubject(subject: Readable | Transform | Writable): TestPipeline;
 }
 

plugins/search-backend-node/src/test-utils/TestPipeline.ts

@@ -37,6 +37,35 @@ export type TestPipelineResult = {
 
 /**
  * Test utility for Backstage Search collators, decorators, and indexers.
+ *
+ * @example
+ * An example test checking that a collator provides expected documents.
+ * ```
+ * it('provides expected documents', async () => {
+ *   const testSubject = await yourCollatorFactory.getCollator();
+ *   const pipeline = TestPipeline.fromCollator(testSubject);
+ *
+ *   const { documents } = await pipeline.execute();
+ *
+ *   expect(documents).toHaveLength(2);
+ * })
+ * ```
+ *
+ * @example
+ * An example test checking that a decorator behaves as expected.
+ * ```
+ * it('filters private documents', async () => {
+ *   const testSubject = await yourDecoratorFactory.getDecorator();
+ *   const pipeline = TestPipeline
+ *     .fromDecorator(testSubject)
+ *     .withDocuments([{ title: 'Private', location: '/private', text: '' }]);
+ *
+ *   const { documents } = await pipeline.execute();
+ *
+ *   expect(documents).toHaveLength(0);
+ * })
+ * ```
+ *
  * @public
  */
 export class TestPipeline {
@@ -60,6 +89,9 @@ export class TestPipeline {
 
   /**
    * Provide the collator, decorator, or indexer to be tested.
+   *
+   * @deprecated Use `fromCollator`, `fromDecorator` or `fromIndexer` static
+   *   methods to create a test pipeline instead.
    */
   static withSubject(subject: Readable | Transform | Writable) {
     if (subject instanceof Transform) {
@@ -79,6 +111,51 @@ export class TestPipeline {
     );
   }
 
+  /**
+   * Create a test pipeline given a collator you want to test.
+   */
+  static fromCollator(collator: Readable) {
+    return new TestPipeline({ collator });
+  }
+
+  /**
+   * Add a collator to the test pipeline.
+   */
+  withCollator(collator: Readable): this {
+    this.collator = collator;
+    return this;
+  }
+
+  /**
+   * Create a test pipeline given a decorator you want to test.
+   */
+  static fromDecorator(decorator: Transform) {
+    return new TestPipeline({ decorator });
+  }
+
+  /**
+   * Add a decorator to the test pipeline.
+   */
+  withDecorator(decorator: Transform): this {
+    this.decorator = decorator;
+    return this;
+  }
+
+  /**
+   * Create a test pipeline given an indexer you want to test.
+   */
+  static fromIndexer(indexer: Writable) {
+    return new TestPipeline({ indexer });
+  }
+
+  /**
+   * Add an indexer to the test pipeline.
+   */
+  withIndexer(indexer: Writable): this {
+    this.indexer = indexer;
+    return this;
+  }
+
   /**
    * Provide documents for testing decorators and indexers.
    */