diff --git a/.changeset/search-tofu-panaeng.md b/.changeset/search-tofu-panaeng.md new file mode 100644 index 0000000000..1f8bbf6a7b --- /dev/null +++ b/.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. diff --git a/plugins/search-backend-node/api-report.md b/plugins/search-backend-node/api-report.md index 62a4eabc26..734bf6e1c0 100644 --- a/plugins/search-backend-node/api-report.md +++ b/plugins/search-backend-node/api-report.md @@ -173,7 +173,14 @@ export type ScheduleTaskParameters = { // @public export class TestPipeline { execute(): Promise; + 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; } diff --git a/plugins/search-backend-node/src/test-utils/TestPipeline.ts b/plugins/search-backend-node/src/test-utils/TestPipeline.ts index 00dd9b3755..33097daae9 100644 --- a/plugins/search-backend-node/src/test-utils/TestPipeline.ts +++ b/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. */