sandbox/proposal_regressiontestframwork.moin

   1 ## This will eventually do to wiki.debian.org/RegressionTestFramework
   2
   3  * '''Created''': <<Date(2010-10-07)>>
   4  * '''Contributors''': MichaelHanke
   5  * '''Packages affected''':
   6  * '''See also''':
   7
   8 == Summary ==
   9
  10 This specification describes conventions and tools that allow Debian to
  11 distribute and run regression test batteries developed by upstream or
  12 Debian developers in a uniform fashion.
  13
  14 == Rationale ==
  15
  16 Ideally software packaged for Debian comes with an exhaustive test suite that
  17 can be used to determine whether this software works as expected on the Debian
  18 platform. However, especially for complex software, these test suites are often
  19 resource hungry (CPU time, memory, diskspace, network bandwidth) and cannot be
  20 ran at package build time by buildds. Consequently, test suites are typically
  21 only utilized by the respective packager on a particular machine, before
  22 uploading a new version to the archive.
  23
  24 However, Debian is an integrated system and packaged software is typically made
  25 to rely on functionality provided by other Debian packages (e.g. shared
  26 libraries) instead of shipping duplicates with different versions in every
  27 package -- for many good reasons. Unfortunately, there is also a downside to
  28 this: Debian packages often use 3rd-party tools with different versions than
  29 those tested by upstream, and moreover, the actual versions of dependencies
  30 might change frequently between to subsequent uploads of a package.  Currently
  31 a change in a dependency that introduces an incompatibility cannot be detected
  32 reliably (before users have filed a bug report) -- even if upstream provides a
  33 test suite that would have caught the breakage. Although there are archive-wide
  34 QA efforts (e.g. constantly rebuilding all packages) these tests can only
  35 detect API/ABI breakage or functionality tested during build-time checks --
  36 they are not exhaustive for the aforementioned reasons.
  37
  38 This is a proposal to, first of all, package upstream test suites in a way that
  39 they can be used to run expensive archive-wide QA tests. However, this is also
  40 a proposal to establish means to test interactions of software from multiple
  41 Debian packages and test proper, continued, integration into the Debian system.
  42
  43 == Use Cases ==
  44
  45   * Moritz is a member of the security team. Whenever he applies a patch to fix
  46     a security issue he wants to make sure that the behavior of the software
  47     remains unchanged. However, in general he only has access to test cases that
  48     are included in the source package (if any). In the absence of proper tests
  49     he can only either assume that is would work (bad by design), or rely on the
  50     respective package maintainer to run the appropriate tests (introduces
  51     delays). A packaged exhaustive regression test suite would allow Moritz to
  52     perform comprehensive testing on his own and release the fixed package as
  53     soon as the tests pass.
  54
  55   * Michael is a Debian package maintainer that takes care of three packages
  56     each providing a data format conversion utility. While all three tools have
  57     their merits there is also lots of overlap. For example, given a particular
  58     data file they should all generate identical output. With a Debian
  59     regression test framework, Michael can write and package cross-package test
  60     suites to ensure that this promise is fulfilled at any time. Moreover,
  61     Michael can also develop/package "pipeline" tests that ensure proper
  62     functioning of multi-stage/package processing pipelines. For example,
  63     testing a whole processing stream from a raw data format conversion, feeding
  64     into an analysis to into a visualization package.
  65
  66   * Albert is a scientist using Debian for his research activities. The
  67     developers of his favorite software tell him to rather use the GreenPants
  68     distribution, because they cannot guarantee that their software works
  69     properly on Debian. The reason their giving is that Debian has a different
  70     version of a numerical library that hasn't been "tested" by the authors.
  71     With packaged regression test suites Albert can run, at any given point,
  72     a complete test of his Debian system to ensure that everything is working
  73     properly given the exact set of base libraries installed at this very moment.
  74     This includes the test suite of the authors of his favorite software, but
  75     also all distribution test suites written by Debian developers (see above).
  76
  77   * Finally, Lucas likes to run all kinds of tests on all packages in the Debian
  78     archive. However, they are mostly concerned with individual packages. A
  79     Debian-wide regression test framework would allow Lucas to execute complex
  80     tests (suites for individual packages, interoperability tests, or
  81     comparative) in an automated fashion, and file bug reports against the
  82     respective packages whenever something fails.
  83
  84 == Scope ==
  85
  86 This specification is applicable to all Debian packages, and Debian as a whole.
  87
  88 == Design ==
  89
  90 A specification should be built with the following considerations:
  91
  92   * The person implementing it may not be the person writing it. It should be
  93   * clear enough for someone to be able to read it and have a clear path
  94   * towards implementing it. If it doesn't, it needs more detail.
  95
  96   * That the use cases covered in the specification should be practical
  97   * situations, not contrived issues.
  98
  99   * Limitations and issues discovered during the creation of a specification
 100   * should be clearly pointed out so that they can be dealt with explicitly.
 101
 102   * If you don't know enough to be able to competently write a spec, you should
 103   * either get help or research the problem further. Avoid spending time making
 104   * up a solution: base yourself on your peers' opinions and prior work.
 105
 106 Specific issues related to particular sections are described further below.
 107
 108 === Implementation Plan ===
 109
 110 This section is usually broken down into subsections, such as the packages
 111 being affected, data and system migration where necessary, user interface
 112 requirements and pictures     (photographs of drawings on paper work well).
 113
 114 == Implementation ==
 115
 116 To implement a specification, the developer should observe the use cases
 117 carefully, and follow the design specified. He should make note of places in
 118 which he has strayed from the design section, adding rationale describing why
 119 this happened. This is important so that next iterations of this specification
 120 (and new specifications that touch upon this subject) can use the specification
 121 as a reference.
 122
 123 The implementation is very dependent on the type of feature to be implemented.
 124 Refer to the team leader for further suggestions and guidance on this topic.
 125
 126 == Outstanding Issues ==
 127
 128 The specification process requires experienced people to drive it. More
 129 documentation on the process should be produced.
 130
 131 The drafting of a specification requires english skills and a very good
 132 understanding of the problem. It must also describe things to an extent that
 133 someone else could implement. This is a difficult set of conditions to ensure
 134 throughout all the specifications added.
 135
 136 There is a lot of difficulty in gardening obsolete, unwanted and abandoned
 137 specifications in the Wiki.
 138
 139 == BoF agenda and discussion ==
 140
 141 Possible meetings where this specification will be discussed.
 142 ----
 143 CategorySpec
 144