@vendure/docs 0.0.0-202601161541

package/docs/guides/developer-guide/strategies-configurable-operations/index.mdx

@@ -0,0 +1,373 @@
+---
+title: 'Strategies & Configurable Operations'
+sidebar_position: 4
+---
+
+Vendure is built to be highly configurable and extensible. Two methods of providing this extensibility are **strategies** and **configurable operations**.
+
+## Strategies
+
+A strategy is named after the [Strategy Pattern](https://en.wikipedia.org/wiki/Strategy_pattern), and is a way of providing
+a pluggable implementation of a particular feature. Vendure makes heavy use of this pattern to delegate the implementation
+of key points of extensibility to the developer.
+
+Examples of strategies include:
+
+- [`OrderCodeStrategy`](/reference/typescript-api/orders/order-code-strategy/) - determines how order codes are generated
+- [`StockLocationStrategy`](/reference/typescript-api/products-stock/stock-location-strategy/) - determines which stock locations are used to fulfill an order
+- [`ActiveOrderStrategy`](/reference/typescript-api/orders/active-order-strategy/) - determines how the active order in the Shop API is selected
+- [`AssetStorageStrategy`](/reference/typescript-api/assets/asset-storage-strategy/) - determines where uploaded assets are stored
+- [`GuestCheckoutStrategy`](/reference/typescript-api/orders/guest-checkout-strategy/) - defines rules relating to guest checkouts
+- [`OrderItemPriceCalculationStrategy`](/reference/typescript-api/orders/order-item-price-calculation-strategy/) - determines how items are priced when added to the order
+- [`TaxLineCalculationStrategy`](/reference/typescript-api/tax/tax-line-calculation-strategy/) - determines how tax is calculated for an order line
+
+As an example, let's take the [`OrderCodeStrategy`](/reference/typescript-api/orders/order-code-strategy/). This strategy
+determines how codes are generated when new orders are created. By default, Vendure will use the built-in `DefaultOrderCodeStrategy`
+which generates a random 16-character string.
+
+What if you need to change this behavior? For instance, you might have an existing back-office system that is responsible
+for generating order codes, which you need to integrate with. Here's how you would do this:
+
+```ts title="src/config/my-order-code-strategy.ts"
+import { OrderCodeStrategy, RequestContext } from '@vendure/core';
+import { OrderCodeService } from '../services/order-code.service';
+
+export class MyOrderCodeStrategy implements OrderCodeStrategy {
+
+    private orderCodeService: OrderCodeService;
+
+    init(injector) {
+        this.orderCodeService = injector.get(OrderCodeService);
+    }
+
+    async generate(ctx: RequestContext): string {
+        return this.orderCodeService.getNewOrderCode();
+    }
+}
+```
+
+:::info
+
+All strategies can make use of existing services by using the `init()` method. This is because all strategies
+extend the underlying [`InjectableStrategy` interface](/reference/typescript-api/common/injectable-strategy). In
+this example we are assuming that we already created an `OrderCodeService` which contains all the specific logic for
+connecting to our backend service which generates the order codes.
+
+:::
+
+We then need to pass this custom strategy to our config:
+
+```ts title="src/vendure-config.ts"
+import { VendureConfig } from '@vendure/core';
+import { MyOrderCodeStrategy } from '../config/my-order-code-strategy';
+
+export const config: VendureConfig = {
+    // ...
+    orderOptions: {
+        // highlight-next-line
+        orderCodeStrategy: new MyOrderCodeStrategy(),
+    },
+}
+```
+
+### Strategy lifecycle
+
+Strategies can use two optional lifecycle methods:
+
+- `init(injector: Injector)` - called during the bootstrap phase when the server or worker is starting up.
+This is where you can inject any services which you need to use in the strategy. You can also perform any other setup logic
+needed, such as instantiating a connection to an external service.
+- `destroy()` - called during the shutdown of the server or worker. This is where you can perform any cleanup logic, such as
+closing connections to external services.
+
+### Passing options to a strategy
+
+Sometimes you might want to pass some configuration options to a strategy.
+For example, imagine you want to create a custom [`StockLocationStrategy`](/reference/typescript-api/products-stock/stock-location-strategy/) which
+selects a location within a given proximity to the customer's address. You might want to pass the maximum distance to the strategy
+in your config:
+
+```ts title="src/vendure-config.ts"
+import { VendureConfig } from '@vendure/core';
+import { MyStockLocationStrategy } from '../config/my-stock-location-strategy';
+
+export const config: VendureConfig = {
+    // ...
+    catalogOptions: {
+        // highlight-next-line
+        stockLocationStrategy: new MyStockLocationStrategy({ maxDistance: 100 }),
+    },
+}
+```
+
+This config will be passed to the strategy's constructor:
+
+```ts title="src/config/my-stock-location-strategy.ts"
+import  { ID, ProductVariant, RequestContext, StockLevel, StockLocationStrategy } from '@vendure/core';
+
+export class MyStockLocationStrategy implements StockLocationStrategy {
+
+    constructor(private options: { maxDistance: number }) {}
+
+    getAvailableStock(
+        ctx: RequestContext,
+        productVariantId: ID,
+        stockLevels: StockLevel[]
+    ): ProductVariant[] {
+        const maxDistance = this.options.maxDistance;
+        // ... implementation omitted
+    }
+}
+```
+
+## Configurable Operations
+
+Configurable operations are similar to strategies in that they allow certain aspects of the system to be customized. However,
+the main difference is that they can also be _configured_ via the Dashboard. This allows the store owner to make changes to the
+behavior of the system without having to restart the server.
+
+So they are typically used to supply some custom logic that needs to accept configurable arguments which can change
+at runtime.
+
+Vendure uses the following configurable operations:
+
+- [`CollectionFilter`](/reference/typescript-api/configuration/collection-filter/) - determines which products are included in a collection
+- [`PaymentMethodHandler`](/reference/typescript-api/payment/payment-method-handler/) - determines how payments are processed
+- [`PromotionCondition`](/reference/typescript-api/promotions/promotion-condition/) - determines whether a promotion is applicable
+- [`PromotionAction`](/reference/typescript-api/promotions/promotion-action/) - determines what happens when a promotion is applied
+- [`ShippingEligibilityChecker`](/reference/typescript-api/shipping/shipping-eligibility-checker/) - determines whether a shipping method is available
+- [`ShippingCalculator`](/reference/typescript-api/shipping/shipping-calculator/) - determines how shipping costs are calculated
+
+Whereas strategies are typically used to provide a single implementation of a particular feature, configurable operations
+are used to provide a set of implementations which can be selected from at runtime.
+
+For example, Vendure ships with a set of default CollectionFilters:
+
+```ts title="default-collection-filters.ts"
+export const defaultCollectionFilters = [
+    facetValueCollectionFilter,
+    variantNameCollectionFilter,
+    variantIdCollectionFilter,
+    productIdCollectionFilter,
+];
+```
+
+When setting up a Collection, you can choose from these available default filters:
+
+![CollectionFilters](./collection-filters.webp)
+
+When one is selected, the UI will allow you to configure the arguments for that filter:
+
+![CollectionFilters args](./collection-filters-args.webp)
+
+Let's take a look at a simplified implementation of the `variantNameCollectionFilter`:
+
+```ts title="variant-name-collection-filter.ts"
+import { CollectionFilter, LanguageCode } from '@vendure/core';
+
+export const variantNameCollectionFilter = new CollectionFilter({
+    args: {
+        operator: {
+            type: 'string',
+            ui: {
+                component: 'select-form-input',
+                options: [
+                    { value: 'startsWith' },
+                    { value: 'endsWith' },
+                    { value: 'contains' },
+                    { value: 'doesNotContain' },
+                ],
+            },
+        },
+        term: { type: 'string' },
+    },
+    code: 'variant-name-filter',
+    description: [{ languageCode: LanguageCode.en, value: 'Filter by product variant name' }],
+    apply: (qb, args) => {
+        // ... implementation omitted
+    },
+});
+```
+
+Here are the important parts:
+
+- Configurable operations are **instances** of a pre-defined class, and are instantiated before being passed to your config.
+- They must have a `code` property which is a unique string identifier.
+- They must have a `description` property which is a localizable, human-readable description of the operation.
+- They must have an `args` property which defines the arguments which can be configured via the Dashboard. If the operation has no arguments,
+then this would be an empty object.
+- They will have one or more methods that need to be implemented, depending on the type of operation. In this case, the `apply()` method
+is used to apply the filter to the query builder.
+
+### Configurable operation args
+
+The `args` property is an object which defines the arguments which can be configured via the Dashboard. Each property of the `args`
+object is a key-value pair, where the key is the name of the argument, and the value is an object which defines the type of the argument
+and any additional configuration.
+
+As an example let's look at the `dummyPaymentMethodHandler`, a test payment method which we ship with Vendure core:
+
+```ts title="dummy-payment-method.ts"
+import { PaymentMethodHandler, LanguageCode } from '@vendure/core';
+
+export const dummyPaymentHandler = new PaymentMethodHandler({
+    code: 'dummy-payment-handler',
+    description: [/* omitted for brevity */],
+    args: {
+        automaticSettle: {
+            type: 'boolean',
+            label: [
+                {
+                    languageCode: LanguageCode.en,
+                    value: 'Authorize and settle in 1 step',
+                },
+            ],
+            description: [
+                {
+                    languageCode: LanguageCode.en,
+                    value: 'If enabled, Payments will be created in the "Settled" state.',
+                },
+            ],
+            required: true,
+            defaultValue: false,
+        },
+    },
+    createPayment: async (ctx, order, amount, args, metadata, method) => {
+        // Inside this method, the `args` argument is type-safe and will be
+        // an object with the following shape:
+        // {
+        //   automaticSettle: boolean
+        // }
+
+        // ... implementation omitted
+    },
+})
+```
+
+The following properties are used to configure the argument:
+
+#### type
+
+<span class="badge badge--primary">Required</span>
+
+[`ConfigArgType`](/reference/typescript-api/configurable-operation-def/config-arg-type)
+
+The following types are available: `string`, `int`, `float`, `boolean`, `datetime`, `ID`.
+
+#### label
+
+<span class="badge badge--secondary">Optional</span>
+
+[`LocalizedStringArray`](/reference/typescript-api/configurable-operation-def/localized-string-array/)
+
+A human-readable label for the argument. This is used in the Dashboard.
+
+#### description
+
+<span class="badge badge--secondary">Optional</span>
+
+[`LocalizedStringArray`](/reference/typescript-api/configurable-operation-def/localized-string-array/)
+
+A human-readable description for the argument. This is used in the Dashboard as a tooltip.
+
+#### required
+
+<span class="badge badge--secondary">Optional</span>
+
+`boolean`
+
+Whether the argument is required. If `true`, then the Dashboard will not allow the user to save the configuration
+unless a value has been provided for this argument.
+
+#### defaultValue
+
+<span class="badge badge--secondary">Optional</span>
+
+`any` (depends on the `type`)
+
+The default value for the argument. If not provided, then the argument will be `undefined` by default.
+
+#### list
+
+<span class="badge badge--secondary">Optional</span>
+
+`boolean`
+
+Whether the argument is a list of values. If `true`, then the Dashboard will allow the user to add multiple values
+for this argument. Defaults to `false`.
+
+#### ui
+
+<span class="badge badge--secondary">Optional</span>
+
+Allows you to specify the UI component that will be used to render the argument in the Dashboard, by specifying
+a `component` property, and optional properties to configure that component.
+
+```ts
+{
+    args: {
+        operator: {
+            type: 'string',
+            ui: {
+                component: 'select-form-input',
+                options: [
+                    { value: 'startsWith' },
+                    { value: 'endsWith' },
+                    { value: 'contains' },
+                    { value: 'doesNotContain' },
+                ],
+            },
+        },
+    }
+}
+```
+
+A full description of the available UI components can be found in the [Custom Fields guide](/guides/developer-guide/custom-fields/#custom-field-ui).
+
+### Injecting dependencies
+
+Configurable operations are instantiated before being passed to your config, so the mechanism for injecting dependencies
+is similar to that of strategies: namely you use an optional `init()` method to inject dependencies into the operation instance.
+
+The main difference is that the injected dependency cannot then be stored as a class property, since you are not defining
+a class when you define a configurable operation. Instead, you can store the dependency as a closure variable.
+
+Here’s an example of a ShippingCalculator that injects a service which has been defined in a plugin:
+
+```ts title="src/config/custom-shipping-calculator.ts"
+import { Injector, ShippingCalculator } from '@vendure/core';
+import { ShippingRatesService } from './shipping-rates.service';
+
+// We keep reference to our injected service by keeping it
+// in the top-level scope of the file.
+let shippingRatesService: ShippingRatesService;
+
+export const customShippingCalculator = new ShippingCalculator({
+    code: 'custom-shipping-calculator',
+    description: [],
+    args: {},
+
+    init(injector: Injector) {
+        // The init function is called during bootstrap, and allows
+        // us to inject any providers we need.
+        shippingRatesService = injector.get(ShippingRatesService);
+    },
+
+    calculate: async (order, args) => {
+        // We can now use the injected provider in the business logic.
+        const { price, priceWithTax } = await shippingRatesService.getRate({
+            destination: order.shippingAddress,
+            contents: order.lines,
+        });
+
+        return {
+            price,
+            priceWithTax,
+        };
+    },
+});
+```
+
+
+
+

package/docs/guides/developer-guide/testing/index.md

@@ -0,0 +1,254 @@
+---
+title: "Testing"
+showtoc: true
+---
+
+# Testing
+
+Vendure plugins allow you to extend all aspects of the standard Vendure server. When a plugin gets somewhat complex (defining new entities, extending the GraphQL schema, implementing custom resolvers), you may wish to create automated tests to ensure your plugin is correct.
+
+The `@vendure/testing` package gives you some simple but powerful tooling for creating end-to-end tests for your custom Vendure code.
+
+By "end-to-end" we mean we are testing the _entire server stack_ - from API, to services, to database - by making a real API request, and then making assertions about the response. This is a very effective way to ensure that _all_ parts of your plugin are working correctly together.
+
+:::info
+For a working example of a Vendure plugin with e2e testing, see the [real-world-vendure Reviews plugin](https://github.com/vendurehq/real-world-vendure/tree/master/src/plugins/reviews)
+:::
+
+## Usage
+
+### Install dependencies
+
+* [`@vendure/testing`](https://www.npmjs.com/package/@vendure/testing)
+* [`vitest`](https://vitest.dev/) You'll need to install a testing framework. In this example, we will use [Vitest](https://vitest.dev/) as it has very good support for the modern JavaScript features that Vendure uses, and is very fast.
+* [`graphql-tag`](https://www.npmjs.com/package/graphql-tag) This is not strictly required but makes it much easier to create the DocumentNodes needed to query your server.
+* We also need to install some packages to allow us to compile TypeScript code that uses decorators:
+  - `@swc/core`
+  - `unplugin-swc`
+
+```sh
+npm install --save-dev @vendure/testing vitest graphql-tag @swc/core unplugin-swc
+```
+
+### Configure Vitest
+
+Create a `vitest.config.mts` file in the root of your project:
+
+```ts title="vitest.config.mts"
+import path from 'path';
+import swc from 'unplugin-swc';
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+    test: {
+        include: ['**/*.e2e-spec.ts'],
+        typecheck: {
+            tsconfig: path.join(__dirname, 'tsconfig.e2e.json'),
+        },
+    },
+    plugins: [
+        // SWC required to support decorators used in test plugins
+        // See https://github.com/vitest-dev/vitest/issues/708#issuecomment-1118628479
+        // Vite plugin
+        swc.vite({
+            jsc: {
+                transform: {
+                    // See https://github.com/vendurehq/vendure/issues/2099
+                    useDefineForClassFields: false,
+                },
+            },
+        }),
+    ],
+});
+```
+
+and a `tsconfig.e2e.json` tsconfig file for the tests:
+
+```json title="tsconfig.e2e.json"
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "types": ["node"],
+    "lib": ["es2015"],
+    "useDefineForClassFields": false,
+    "skipLibCheck": true,
+    "inlineSourceMap": false,
+    "sourceMap": true,
+    "allowSyntheticDefaultImports": true,
+    "experimentalDecorators": true,
+    "emitDecoratorMetadata": true,
+    "esModuleInterop": true
+  }
+}
+
+```
+
+### Register database-specific initializers
+
+The `@vendure/testing` package uses "initializers" to create the test databases and populate them with initial data. We ship with initializers for `sqljs`, `postgres` and `mysql`. Custom initializers can be created to support running e2e tests against other databases supported by TypeORM. See the [`TestDbInitializer` docs](/reference/typescript-api/testing/test-db-initializer/) for more details.
+
+```ts title="src/plugins/my-plugin/e2e/my-plugin.e2e-spec.ts"
+import {
+    MysqlInitializer,
+    PostgresInitializer,
+    SqljsInitializer,
+    registerInitializer,
+} from '@vendure/testing';
+
+const sqliteDataDir = path.join(__dirname, '__data__');
+
+registerInitializer('sqljs', new SqljsInitializer(sqliteDataDir));
+registerInitializer('postgres', new PostgresInitializer());
+registerInitializer('mysql', new MysqlInitializer());
+```
+
+:::info
+Note re. the `sqliteDataDir`: The first time this test suite is run with the `SqljsInitializer`, the populated data will be saved into an SQLite file, stored in the directory specified by this constructor arg. On subsequent runs of the test suite, the data-population step will be skipped and the initial data directly loaded from the SQLite file. This method of caching significantly speeds up the e2e test runs. All the .sqlite files created in the `sqliteDataDir` can safely be deleted at any time.
+:::
+
+### Create a test environment
+
+The `@vendure/testing` package exports a [`createTestEnvironment` function](/reference/typescript-api/testing/create-test-environment/) which is used to set up a Vendure server and GraphQL clients to interact with both the Shop and Admin APIs:
+
+```ts title="src/plugins/my-plugin/e2e/my-plugin.e2e-spec.ts"
+import { createTestEnvironment, testConfig } from '@vendure/testing';
+import { describe } from 'vitest';
+import { MyPlugin } from '../my-plugin.ts';
+
+describe('my plugin', () => {
+
+    const {server, adminClient, shopClient} = createTestEnvironment({
+        ...testConfig,
+        plugins: [MyPlugin],
+    });
+
+});
+```
+
+Notice that we pass a [`VendureConfig`](/reference/typescript-api/configuration/vendure-config/) object into the `createTestEnvironment` function. The testing package provides a special [`testConfig`](/reference/typescript-api/testing/test-config/) which is pre-configured for e2e tests, but any aspect can be overridden for your tests. Here we are configuring the server to load the plugin under test, `MyPlugin`. 
+
+:::caution
+**Note**: If you need to deeply merge in some custom configuration, use the [`mergeConfig` function](/reference/typescript-api/configuration/merge-config/) which is provided by `@vendure/core`.
+:::
+
+### Initialize the server
+
+The [`TestServer`](/reference/typescript-api/testing/test-server/) needs to be initialized before it can be used. The `TestServer.init()` method takes an options object which defines how to populate the server:
+
+```ts title="src/plugins/my-plugin/e2e/my-plugin.e2e-spec.ts"
+import { beforeAll, afterAll } from 'vitest';
+import { myInitialData } from './fixtures/my-initial-data.ts';
+
+// ...
+
+beforeAll(async () => {
+    await server.init({
+        productsCsvPath: path.join(__dirname, 'fixtures/e2e-products.csv'),
+        initialData: myInitialData,
+        customerCount: 2,
+    });
+    await adminClient.asSuperAdmin();
+}, 60000);
+
+afterAll(async () => {
+    await server.destroy();
+});
+```
+
+An explanation of the options:
+
+* `productsCsvPath` This is a path to an optional CSV file containing product data. See [Product Import Format](/guides/developer-guide/importing-data/#product-import-format). You can see [an example used in the Vendure e2e tests](https://github.com/vendurehq/vendure/blob/master/packages/core/e2e/fixtures/e2e-products-full.csv) to get an idea of how it works. To start with you can just copy this file directly and use it as-is.
+* `initialData` This is an object which defines how other non-product data (Collections, ShippingMethods, Countries etc.) is populated. See [Initial Data Format](/guides/developer-guide/importing-data/#initial-data). You can [copy this example from the Vendure e2e tests](https://github.com/vendurehq/vendure/blob/master/e2e-common/e2e-initial-data.ts)
+* `customerCount` Specifies the number of fake Customers to create. Defaults to 10 if not specified.
+
+### Write your tests
+
+Now we are all set up to create a test. Let's test one of the GraphQL queries used by our fictional plugin:
+
+```ts title="src/plugins/my-plugin/e2e/my-plugin.e2e-spec.ts"
+import gql from 'graphql-tag';
+import { it, expect, beforeAll, afterAll } from 'vitest';
+import { myInitialData } from './fixtures/my-initial-data.ts';
+
+it('myNewQuery returns the expected result', async () => {
+    adminClient.asSuperAdmin(); // log in as the SuperAdmin user
+
+    const query = gql`
+    query MyNewQuery($id: ID!) {
+      myNewQuery(id: $id) {
+        field1
+        field2
+      }
+    }
+  `;
+    const result = await adminClient.query(query, {id: 123});
+
+    expect(result.myNewQuery).toEqual({ /* ... */})
+});
+```
+
+Running the test will then assert that your new query works as expected.
+
+### Run your tests
+
+All that's left is to run your tests to find out whether your code behaves as expected!
+
+:::caution
+**Note:** When using **Vitest** with multiple test suites (multiple `.e2e-spec.ts` files), it will attempt to run them in parallel. If all the test servers are running
+on the same port (the default in the `testConfig` is `3050`), then this will cause a port conflict. To avoid this, you can manually set a unique port for each test suite. Be aware that `mergeConfig` is used here:
+
+```ts title="src/plugins/my-plugin/e2e/my-plugin.e2e-spec.ts"
+import { createTestEnvironment, testConfig } from '@vendure/testing';
+import { mergeConfig } from "@vendure/core";
+import { describe } from 'vitest';
+import { MyPlugin } from '../my-plugin.ts';
+
+describe('my plugin', () => {
+
+    const {server, adminClient, shopClient} = createTestEnvironment(mergeConfig(testConfig, {
+        // highlight-start
+        apiOptions: {
+            port: 3051,
+        },
+        // highlight-end
+        plugins: [MyPlugin],
+    }));
+
+});
+```
+:::
+
+## Accessing internal services
+
+It is possible to access any internal service of the Vendure server via the `server.app` object, which is an instance of the NestJS `INestApplication`.
+
+For example, to access the `ProductService`:
+
+```ts title="src/plugins/my-plugin/e2e/my-plugin.e2e-spec.ts"
+import { createTestEnvironment, testConfig } from '@vendure/testing';
+import { describe, beforeAll } from 'vitest';
+import { MyPlugin } from '../my-plugin.ts';
+
+describe('my plugin', () => {
+    
+    const { server, adminClient, shopClient } = createTestEnvironment({
+        ...testConfig,
+        plugins: [MyPlugin],
+    });
+    
+    // highlight-next-line
+    let productService: ProductService;
+    
+    beforeAll(async () => {
+        await server.init({
+            productsCsvPath: path.join(__dirname, 'fixtures/e2e-products.csv'),
+            initialData: myInitialData,
+            customerCount: 2,
+        });
+        await adminClient.asSuperAdmin();
+        // highlight-next-line
+        productService = server.app.get(ProductService);
+    }, 60000);
+
+});
+```