Re: [PATCH v3 54/54] docs/devel: testing: Document writing portable test cases

[Thomas Huth]

On 25/09/2022 13.30, Bin Meng wrote:
> From: Bin Meng <bin.meng@windriver.com>
>
> Update the best practices of how to write portable test cases that
> can be built and run successfully on both Linux and Windows hosts.
>
> Signed-off-by: Bin Meng <bin.meng@windriver.com>
> Reviewed-by: Marc-André Lureau <marcandre.lureau@redhat.com>
> ---
>
> (no changes since v3)
>
> Changes in v2:
> - Minor wording changes
> - Drop patches that were already applied in the mainline
> - Drop patch: "qga/commands-posix-ssh: Use g_mkdir_with_parents()"
> - Drop patch: "tests: Skip iotests and qtest when '--without-default-devices'"
> - Drop patch: "tests/qtest: Fix ERROR_SHARING_VIOLATION for win32"
>
>   docs/devel/testing.rst | 30 ++++++++++++++++++++++++++++++
>   1 file changed, 30 insertions(+)
>
> diff --git a/docs/devel/testing.rst b/docs/devel/testing.rst
> index aea5b42356..0eae9c4654 100644
> --- a/docs/devel/testing.rst
> +++ b/docs/devel/testing.rst
> @@ -115,6 +115,36 @@ check-block
>   are in the "auto" group).
>   See the "QEMU iotests" section below for more information.

Looks like you've added the new text after the "check-block" section ... 
could you please add it after the "QTest" section instead?

> +Writing portable test cases
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~
> +Both unit tests and qtests can run on POSIX hosts as well as a Windows host.

Nit: better use plural in both cases: "on POSIX hosts as well as Windows hosts".

> +Care must be taken when writing portable test cases that can be built and run
> +successfully on various hosts. The following are some best practices:

Maybe better (but I'm not a native speaker either): "The following list 
shows some best practices"

> +* Use portable APIs from glib whenever necessary, e.g.: g_setenv(),
> +  g_mkdtemp(), g_mkdir().
> +* Avoid using hardcoded /tmp for temporary file directory.
> +  Use g_get_tmp_dir() instead.
> +* Bear in mind that Windows has different special string representation for
> +  stdin/stdout/stderr and null devices. For example if your test case uses
> +  "/dev/fd/2" and "/dev/null" on Linux, remember to use "2" and "nul" on
> +  Windows instead. Also IO redirection does not work on Windows, so avoid
> +  using "2>nul" whenever necessary.
> +* If your test cases uses the blkdebug feature, use relative path to pass
> +  the config and image file paths in the command line as Windows absolute
> +  path contains the delimeter ":" which will confuse the blkdebug parser.

s/delimeter/delimiter/

> +* Use double quotes in your extra QEMU commmand line in your test cases
> +  instead of single quotes, as Windows does not drop single quotes when
> +  passing the command line to QEMU.
> +* Windows opens a file in text mode by default, while a POSIX compliant
> +  implementation treats text files and binary files the same. So if your
> +  test cases opens a file to write some data and later wants to compare the
> +  written data with the original one, be sure to pass the letter 'b' as
> +  part of the mode string to fopen(), or O_BINARY flag for the open() call.
> +* If a certain test case can only run on POSIX or Linux hosts, use a proper
> +  #ifdef in the codes. If the whole test suite cannot run on Windows, disable
> +  the build in the meson.build file.
> +
>   QEMU iotests
>   ------------
>   

 Thomas