[igt-dev] [RFC] IGT Subtest Documentation

[Katarzyna Dec]

On Wed, Jun 05, 2019 at 01:06:42PM +0300, Arkadiusz Hiler wrote:
> On Mon, Jun 03, 2019 at 04:51:46PM +0200, Katarzyna Dec wrote:
> > Wow Arek! That sound awsome. I hope that something in that shape will be
> > introduced to igt and respected.
> 
> > Do we want somehow enforce on adding docs?
> 
> Yep, we will have a requirement for all the new tests to be described
> (if it makes sense).
> 
> > How deep in description we should be? Like - this test is 'doing
> > reset' or is checking HW/SW feature?
> 
> Very "shallow". As I have said - I don't want C translated to english.
> I want to have the intention of test captured.
> 
> Let me give you an rough example:
> 
> ####################### kms_hdmi_inject.c #############################
> 
> igt_describe_test("Test that in-kernel EDID parsing is producing "
> 		  "expected results by forcing a HDMI connector with "
> 		  "a known EDID and checking that the metadata exposed "
> 		  "to user space matches.");
> igt_main
> {
> 	igt_describe("Make sure that 4K modes exposed by DRM match the
> 		     "forced EDID and the modesetting using it works.");
> 	igt_subtest("inject-4k")
> 		hdmi_inject_4k(drm_fd, connector);
> 
> 	igt_describe("Make sure that audio information exposed by ALSA "
> 	             "match the forced EDID.");
> 	igt_subtest("inject-audio")
> 		hdmi_inject_audio(drm_fd, connector);
> }
> 
> #######################################################################
> 
> This is already on the verge of translation, but that's because the test
> are extremely simple. If we would expand the test a bit (let's say to
> test more than a single EDID or do more detailed checks), the
> description would stay true and would not require changing.
> 
> Another example, for a much more complex test could be something like this:
> 
> igt at kms_cursor_legacy@cursor-vs-flip-*
> "Check that the asynchronous legacy cursor updates do not stall for a
> page-flip, by making sure that we can squeeze many cursor updates
> in-between flips."
> 
> The final series will come with some documentation on how to write good
> descriptions (with list of dos and don'ts) and few a examples.
> 
> We can hold a biksheeding festival there :-)
> 
> -- 
> Cheers,
> Arek
Good explanation, thanks for that.
So when do we start? :)
Kasia :)