<div dir="ltr"><div dir="ltr"><br></div><br><div class="gmail_quote gmail_quote_container"><div dir="ltr" class="gmail_attr">On Tue, Jul 15, 2025 at 2:57 AM Paul Szczepanek <<a href="mailto:paul.szczepanek@arm.com">paul.szczepanek@arm.com</a>> wrote:<br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">Hi all,<br>
<br>
Now that we've written a significant number of tests and developed a<br>
consistent usage pattern, I think it's a good time to take the next step<br>
toward project maturity: establishing a stable, well-defined API that<br>
developers can rely on across releases.<br></blockquote><div><br></div><div>Agree</div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">
<br>
We got some comments from the devs present at the last DPDK summit and<br>
they are valuable guidance on what direction you'd like the framework to<br>
go and we're taking them onboard to shape our roadmap. Very much related<br>
to that we'd appreciate any comments on what you'd like to see in the API.<br>
<br>
API proposal goal<br>
<br>
Split framework internals from functions intended for use by test writers.<br>
<br>
This API would offer:<br>
- Discoverability of available functionality<br>
- Clear boundaries between public/test-facing APIs and internal<br>
framework logic<br>
- A stable interface for writing and maintaining tests<br>
- A DPDK-style release cadence and compatibility guarantee (i.e., write<br>
once, run future-proof)<br></blockquote><div><br></div><div>The notes about making the API stable make sense:</div><div>1. So, is there a suggestion here that the API can be broken once per year, and that would be a new policy? Would that happen at a .11 release with your proposal?</div><div>2. I assume I can add functions to a DTS API module, but cannot remove/change existing ones during a stable period?</div><div>3. I guess we can either have reviews and maintainer review enforce the API stability, or we can develop some checks that will try to enforce the API stability. Do you have a preference?</div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">
<br>
With this split, DTS becomes effectively self-documenting — users can<br>
explore and use only what’s in the api.<br>
<br>
Technical Summary<br>
<br>
Introduce a dedicated api/ directory that contains a small, focused set<br>
of modules exposing all the functionality needed to write tests.<br>
<br>
All test execution logic and framework internals will remain private and<br>
continue to live in framework/, where we can iterate freely without<br>
breaking user tests.<br></blockquote><div><br></div><div>Sounds good.</div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">
<br>
The new api/ modules will be stateless, accessing test context via<br>
get_ctx().<br>
<br>
Users will import only what they need:<br>
<br>
> from api import dts, tg, sut<br>
<br>
and use it as module functions<br>
<br>
> tg.send_packet(...)<br>
> dts.verify(...)<br>
> testpmd = sut.testpmd_create(...)<br>
<br>
Because the modules are stateless and the context is already managed by<br>
the runner, the changes to the existing framework will be minimal.<br>
<br>
Initially, we’ll have three modules in api/: dts, tg, and sut. This can<br>
grow as needed.<br></blockquote><div><br></div><div>Makes sense, although I think (and hope) it will not need to grow much. Keeping in mind that we we want the journey from "not knowing DTS" to "having written a testsuite" to be as short as possible.</div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">
<br>
The goal of this approach is to provide a clean, intuitive developer<br>
experience when doing API calls, with logical namespacing and good IDE<br>
support for discoverability and usability.<br>
<br>
Next Steps<br>
<br>
Feedback is very welcome — feel free to reply here or on our slack<br>
channel #dts-dev. If you would like to join an upcoming DTS meeting on<br>
Thursday to discuss this live send us and email (or ask on slack) to get<br>
an invite.<br>
<br>
After initial discussions I will send a small RFC patch with framework<br>
changes only allowing further comments.<br>
<br>
I will follow up with a V1 patch introducing the new API and updating<br>
all existing tests to use it.<br>
<br>
Thanks for reading! I'm excited about getting DTS in more hands and hope<br>
this will make it even easier for contributors and users to write<br>
robust, maintainable tests.<br>
<br>
Kindest regards,<br>
Paul<br>
</blockquote></div></div>