Testing

Although the presentation framework itself is thoroughly tested, consumers should still verify they get expected results for their iModel + ruleset combinations. The @itwin/presentation-testing package is delivered purely for that reason.

The package delivers an API that allows creating hierarchies for supplied iModels and rulesets. Consumers can then verify the result using tools of their liking. Our recommendation is to use snapshot testing for 2 reasons:

1. Resulting hierarchies get rather large — testing them in code might be difficult.
2. Snapshots protect against regressions.

Example

An example of setting up snapshot tests with the @itwin/presentation-testing package:

1. Initialize testing library and open iModel

   // initialize presentation-testing
   await initialize();
   
   // set up for testing iModel presentation data
   iModel = await SnapshotConnection.openFile(iModelPath);
   

2. Generate and verify results:

   2.1. Hierarchies:

   it("generates correct hierarchy", async function () {
     const builder = new HierarchyBuilder({ imodel: iModel });
   
     // generate the hierarchy using our custom ruleset
     const hierarchy = await builder.createHierarchy(MY_HIERARCHY_RULESET);
   
     // verify it through snapshot
     expect(hierarchy).to.matchSnapshot(createSnapshotPath(this.test!, MY_HIERARCHY_RULESET.id), MY_HIERARCHY_RULESET.id);
   });
   

   2.2. Content:

   it("generates correct content", async function () {
     const builder = new ContentBuilder({ imodel: iModel, decimalPrecision: 8 });
   
     // generate content using our custom ruleset
     const myElementKey = { className: "Generic:PhysicalObject", id: Id64.fromLocalAndBriefcaseIds(116, 0) };
     const records = await builder.createContent(MY_CONTENT_RULESET, [myElementKey]);
   
     // verify the records through snapshot
     expect(records).to.matchSnapshot(createSnapshotPath(this.test!, MY_CONTENT_RULESET.id), `${myElementKey.className}-${myElementKey.id}`);
   });
   

3. Close iModel and terminate testing library:

   // close the tested iModel
   await iModel.close();
   
   // terminate presentation-testing
   await terminate();
   

Note: The above example uses mocha and chai-jest-snapshot packages to perform snapshot testing. createSnapshotPath function retrieves a path to the snapshot for the current test.

Things to keep in mind

• Run initialize() before and terminate() after the tests.

• Don't forget to close the iModel connection.

• Ruleset can be provided either as an ID of already registered ruleset or as a Ruleset object. The object can even be imported from a JSON file:

  await builder.createHierarchy(require("rulesets/YourRuleset.json"))
  

Last Updated: 12 February, 2024