## This will eventually do to wiki.debian.org/RegressionTestFramework * '''Created''': <> * '''Contributors''': MichaelHanke * '''Packages affected''': * '''See also''': == Summary == This specification describes conventions and tools that allow Debian to distribute and run regression test batteries developed by upstream or Debian developers in a uniform fashion. == Rationale == Ideally software packaged for Debian comes with an exhaustive test suite that can be used to determine whether this software works as expected on the Debian platform. However, especially for complex software, these test suites are often resource hungry (CPU time, memory, diskspace, network bandwidth) and cannot be ran at package build time by buildds. Consequently, test suites are only utilized by the packager on a particular machine, before uploading a new version to the archive. However, Debian is an integrated system and packaged software is typically made to rely on functionality provided by other Debian packages (e.g. shared libraries) instead of shipping duplicates with different versions in every package -- for many good reasons. Unfortunately, there is also a downside to this: Debian packages often use 3rd-party tools with different versions than those tested by upstream, and moreover, the actual versions might change frequently between to subsequent uploads of a package. Currently a change in a dependency that introduces an incompatibility cannot be detected reliably (before users have filed a bug report) -- even if upstream provides a testsuite that would have caught the breakage. Although there are archive-wide QA efforts (e.g. constantly rebuilding all packages) these tests can only detect API/ABI breakage or functionality tested during build-time checks -- they are not exhaustive for the aforementioned reasons. This is a proposal to, first of all, package upstream test suites in a way that they can be used to run expensive archive-wide QA tests. However, this is also a proposal to establish means to test interactions of software from multiple Debian packages and test proper, continued, integration into the Debian system. == Use Cases == * Moritz is a member of the security team. Whenever he applies a patch to fix a security issue he wants to make sure that the behavior of the software remains unchanged. However, in general he only has access to test cases that are included in the source package (if any). In the absence of proper tests he can only either assume that is would work (bad by design), or rely on the respective package maintainer to run the appropriate tests (introduces delays). A packaged exhaustive regression test suite would allow Moritz to perform comprehensive testing on his own and release the fixed package as soon as the tests pass. * Michael is a Debian package maintainer that takes care of three packages each providing a data format conversion utility. While all three tools have their merits there is also lots of overlap. For example, given a particular data file they should all generate identical output. With a Debian regression test framework, Michael can write and package cross-package test suites to ensure that this promise is fulfilled at any time. Moreover, Michael can also develop/package "pipeline" tests that ensure proper functioning of multi-stage/package processing pipelines. For example, testing a whole processing stream from a raw data format conversion, feeding into an analysis to into a visualization package. * Albert is a scientist using Debian for his research activities. The developers of his favorite software tell him to rather use the GreenPants distribution, because they cannot guarantee that their software works properly on Debian. The reason their giving is that Debian has a different version of a numerical library that hasn't been "tested" by the authors. With packaged regression test suites Albert can run, at any given point, a complete test of his Debian system to ensure that everything is working properly given the exact set of base library installed at this very moment. This includes the test suite of the authors of his favorite software, but also all distribution test suites written by Debian developers (see above). * Finally, Lucas likes to run all kinds of tests on all packages in the Debian archive. However, they are mostly concerned with individual packages. A Debian-wide regression test framework would allow Lucas to execute complex tests (suites for individual packages, interoperability tests, or comparative) in an automated fashion, and file bug reports against the respective packages whenever something fails. == Scope == This specification is applicable to all Debian packages, and Debian as a whole. == Design == A specification should be built with the following considerations: * The person implementing it may not be the person writing it. It should be * clear enough for someone to be able to read it and have a clear path * towards implementing it. If it doesn't, it needs more detail. * That the use cases covered in the specification should be practical * situations, not contrived issues. * Limitations and issues discovered during the creation of a specification * should be clearly pointed out so that they can be dealt with explicitly. * If you don't know enough to be able to competently write a spec, you should * either get help or research the problem further. Avoid spending time making * up a solution: base yourself on your peers' opinions and prior work. Specific issues related to particular sections are described further below. === Summary === The summary should not attempt to say '''why''' the spec is being defined, just '''what''' is being specified. === Rationale === This should be the description of '''why''' this spec is being defined. === Scope and Use Cases === While not always required, but in many cases they bring much better clarity to the scope and scale of the specification than could be obtained by talking in abstract terms. === Implementation Plan === This section is usually broken down into subsections, such as the packages being affected, data and system migration where necessary, user interface requirements and pictures (photographs of drawings on paper work well). == Implementation == To implement a specification, the developer should observe the use cases carefully, and follow the design specified. He should make note of places in which he has strayed from the design section, adding rationale describing why this happened. This is important so that next iterations of this specification (and new specifications that touch upon this subject) can use the specification as a reference. The implementation is very dependent on the type of feature to be implemented. Refer to the team leader for further suggestions and guidance on this topic. == Outstanding Issues == The specification process requires experienced people to drive it. More documentation on the process should be produced. The drafting of a specification requires english skills and a very good understanding of the problem. It must also describe things to an extent that someone else could implement. This is a difficult set of conditions to ensure throughout all the specifications added. There is a lot of difficulty in gardening obsolete, unwanted and abandoned specifications in the Wiki. == BoF agenda and discussion == Possible meetings where this specification will be discussed. ---- CategorySpec