Utilities for writing unit tests for DDS in Fluid Framework.
NOTE: This package is private to the @microsoft/fluid-framework repository.
This package is not published.
Use it only in packages in the same pnpm workspace.
Specify workspace:* as the version.
Use this package only as a development dependency or as a dependency of an unpublished package.
gcTestRunner provides a set of tests for validating that the DDSes return correct GC nodes.
To write GC tests for a DDS, call runGCTests with a class that implements the following interface:
export interface IGCTestProvider {
/** The DDS whose GC data is to be verified */
readonly sharedObject: ISharedObject;
/** The expected list of outbound routes from this DDS */
readonly expectedOutboundRoutes: string[];
/** Function that adds routes to Fluid objects to the DDS' data */
addOutboundRoutes(): Promise<void>;
/** Function that deletes routes to Fluid objects to the DDS' data */
deleteOutboundRoutes(): Promise<void>;
/** Function that adds nested handles to the DDS' data */
addNestedHandles(): Promise<void>;
}The caller is responsible for the following:
- Adding and deleting routes to Fluid objects to the DDS which is being tested.
- Adding nested handles to the DDS' data.
- Maintaining the list of expected outbound routes. The tests query this and validates that the GC data returned by the DDS matches these routes.
SharedCell and SharedDirectory have tests that use the gcTestRunner for validating GC data.
This package also provides a generic harness for writing eventual consistency fuzz tests for a DDS.
This model is written using @fluid-private/stochastic-test-utils.
See documentation on createDDSFuzzSuite and DDSFuzzModel for more details.
The harness currently supports testing eventual consistency of op application using Fluid's set of mocks including the reconnect flow.
Set DDSFuzzModel.factory to a DDSFuzzClientFactory provider to construct clients with different DDS options or package versions.
You define the configuration values and supply a callback that resolves each value to an IChannelFactory.
The factories must expose a common channel API that your model can use.
Use generateClientConfiguration(random, client) to select a configuration with seeded randomness.
The client context includes clientId and isSummarizer, so you can give the summarizer a specific configuration.
Use getFactory(clientConfiguration) to resolve the recorded value without making new random choices.
Configuration values use the same Fluid serialization as other fuzz operations, including support for IFluidHandle values.
Use the same serializable shapes as operation data; a configuration provider must return a value other than undefined.
Do not mutate configurations after they are generated.
For example, a model with an existing workload can select between two compatible factories:
type ClientConfiguration = { version: "current" | "previous" };
type Factory = typeof currentFactory | typeof previousFactory;
type State = DDSFuzzTestState<Factory, ClientConfiguration>;
const model: DDSFuzzModel<Factory, Operation, State> = {
...existingModel,
factory: {
generateClientConfiguration: (random, { isSummarizer }) => ({
version: isSummarizer ? "current" : random.pick(["current", "previous"]),
}),
getFactory: ({ version }) =>
version === "current" ? currentFactory : previousFactory,
},
};Your resolver can also construct a factory from options stored in the configuration.
The provider is the model's factory; no separate default factory is needed.
For a single configuration, continue to pass an IChannelFactory directly as model.factory.
Use isChannelFactory(model.factory) to narrow the factory type when integrating a model with code that requires a direct IChannelFactory.
The harness records the initial clients in an initialize operation.
It records subsequent choices in attach.clients and addClient.clientConfiguration.
Each created client exposes its configuration as client.clientConfiguration, including in clientCreate listeners.
The testStart event occurs once, after the starting clients are created and before the workload generator is created.
This lifecycle is the same for both factory forms and for replay.
Rehydration and stash restoration retain the original client's configuration, even if the client gets a new name.
If you pass an IChannelFactory directly, the harness omits details about configuration for each client in its operations.
The same configuration mechanism is available in SquashFuzzModel.
The generic aspects of this model could be improved to fuzz test correctness a few other general concerns DDS authors have:
- Summarization correctness
- Offline (
applyStashedOpimplementation)
You can contribute to Fluid Framework in these ways:
- Answer questions in GitHub Discussions.
- Submit bug reports and help verify fixes.
- Review source code changes.
- Contribute bug fixes.
For detailed instructions, read the repo documentation.
This project follows the Microsoft Open Source Code of Conduct. For more information, read the Code of Conduct frequently asked questions. For questions or comments, contact opencode@microsoft.com.
This project may contain Microsoft trademarks or logos for Microsoft projects, products, or services. Use of these trademarks or logos must follow Microsoft’s Trademark & Brand Guidelines. Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship.
Read the Fluid Framework documentation for information about Fluid Framework concepts and APIs.
To request information that the documentation does not contain, create an issue.
This project may contain Microsoft trademarks or logos for Microsoft projects, products, or services.
Use of these trademarks or logos must follow Microsoft's Trademark & Brand Guidelines.
Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship.