Skip to content

Tree schema open polymorphism examples #25805

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
CraigMacomber merged 11 commits into from
Nov 4, 2025
Merged

Tree schema open polymorphism examples #25805

Show file tree
Hide file tree
Changes from 6 commits
Commits
Show all changes
11 commits
Select commit Hold shift + click to select a range
3ea86d7
Add open polymorphism examples
CraigMacomber Oct 29, 2025
2c9808e
Merge branch 'main' of https://github.com/microsoft/FluidFramework in…
CraigMacomber Oct 30, 2025
f3de1ed
Merge branch 'main' of https://github.com/microsoft/FluidFramework in…
CraigMacomber Oct 30, 2025
019a6ca
Test details of InsertableTypedNode
CraigMacomber Oct 31, 2025
afb9809
Merge branch 'main' of https://github.com/microsoft/FluidFramework in…
CraigMacomber Nov 3, 2025
8c1c6cf
Merge branch 'main' into OpenPolcyExamples
CraigMacomber Nov 3, 2025
5d752c5
Update packages/dds/tree/src/test/README.md
CraigMacomber Nov 3, 2025
ba7fbdd
Apply suggestions from code review
CraigMacomber Nov 3, 2025
993e0f1
Fix test readme.
CraigMacomber Nov 4, 2025
dbdd9e7
Merge branch 'OpenPolcyExamples' of https://github.com/CraigMacomber/…
CraigMacomber Nov 4, 2025
7cf3163
Document scope of test file
CraigMacomber Nov 4, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 12 additions & 0 deletions packages/dds/tree/src/test/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,9 +22,21 @@ Assuming all code has such tests, and only relies of documented behavior of the
In practice, testing of this type will not cover all cases: this is expected.
When a testing gap is found and determined worth covering (for example due to a bug, new code, or audit of coverage), it should always be possible to address it by adding more tests following this pattern (for example regression tests can always be implemented as a `spec` test for the code which contained the bug).
Note that the fact that this approach is always possible does not make it the best approach: using spec tests in this way should be the first option considered, but if a better testing approach is found, it can be used instead as long as it is documented appropriately.
- `integration`: Tests for using multiple APIs together.
If there is a corresponding `spec` file which is sufficiently large in scope, the tests should be placed within it:
only when the tests don't cleanly correspond to a particular source file should a separate `integration` file be created.
When created, the file should be placed in the `src/test` directory's sub folder which is the most nested it can be while still including all the relevant APIs.
For example an example of using `src/thing/foo` with `src/thing/bar` would belong in `src/test/thing` and could be named something like `fooWithBar.example.ts`.
Copy link
Contributor

@Josmithr Josmithr Nov 3, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should this not be a test file? I would have expected fooWithBar.spec.ts or fooWithBar.integration.spec.ts or something.

Copy link
Contributor Author

@CraigMacomber CraigMacomber Nov 3, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This documentation defines them to be test files, so they are. Just above this is the definition of what we mean by ".spec" in a file, and these do not meet that. Nowhere in here (or anywhere that I know of) do we define that files without ".spec" in there name are not test files. Historically we have inaccurately followed that convention throughout our repo in a mostly undocumented way. Here in tree we have a documented policy (this file) and thus can make changes to the convention (as done here).

I don't think there is any value in making every kind of test file include ".spec" in its file name. If we wanted something to put in the name of every test file, we would pick something like ".test" (well we went with /src/test/ as path prefix which also works).

".spec" (which I assume is short for "specification test") can have a more useful meaning (defined above in this file) if we don't stick it on everything.

Copy link
Contributor

@Josmithr Josmithr Nov 3, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fair enough. I guess my real concern is the overloaded use of ".example.ts". We use that below for examples we want to keep up to date. This seems distinct from that. Seems like it should have a different naming convention.

Copy link
Contributor

@Josmithr Josmithr Nov 3, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actually, the new test suite in this PR does use .integration.ts, so I'm guessing this paragraph just needs to be fixed to say that instead of example.ts.

Copy link
Contributor Author

@CraigMacomber CraigMacomber Nov 4, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Oh, .example.ts here is wrong. I was doing that earlier and changed my mind since a lot of examples fit inside of .spec tests. I'll update this

Copy link
Contributor Author

@CraigMacomber CraigMacomber Nov 4, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done.


Any other kinds of test files should be documented when created by adding them to this list.

## Examples

Code showing how to use an API can be included in tests.
Such tests should mention that they are an "example" somewhere in the file name, suite or test name.
These are not intended to serve as tests for the APIs, but are written as tests to ensure the examples stay up to date.
If there is a corresponding `spec` file, the examples should be included within it: only when the examples don't cleanly correspond to a particular source file should a separate `examples` file be created. When created, the file should be places in the `src/test` directory's sub colder which corresponds to the most nested it can be while still including all the relevant APIs. For example an example of using `src/thing/foo` with `src/thing/bar` would belong in `src/test/thing` and could be named something like `fooWithBar.example.ts`.

## Test Tagging

Tests can be [tagged](https://mochajs.org/next/explainers/tagging/).
Expand Down
Loading
Loading