[igt-dev] [RFC] IGT Subtest Documentation

[Arkadiusz Hiler]

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