This initiative aims to improve the quality and stability of Inkscape and to reduce the number of bugs and regressions, especially severe ones.

In a nutshell, the goal is to have '''more of:'''

* Test coverage of source code (unit tests, component/integration tests, end-to-end tests);
* Test automation, developer-friendly testing frameworks and tooling;
* Good practices related to coding and testing;
* Improvements to the code review process and release management;
* Focus on quality, especially during the release period.

In this way, we would like to have '''less of:'''

* Crashes and data loss bugs;
*Reliance on time-consuming manual testing;
* Memory leaks and corruption;
* Glitches, corner cases and difficult-to-reproduce bugs;
* Code fragility due to hidden assumptions and limitations;
* Legacy code;
* Code that nobody understands and maintains.

== Proposed Actions (To Do List)==
#Set up CMake targets and macros to make it easy to create unit tests. Currently, all GTest tests link <code>libinkscape_base</code>, so they are in fact integration tests rather than unit tests. There should be an easy way of explicitly listing one or several cpp files which will be compiled and linked with tests support utilities only (test the functionality '''in isolation'''). Additionally, there needs to be a way to request linking in <code>lib2geom</code> for functionality that requires it.
#Ensure all tests run in debug mode so that failed asserts crash them.
#Create a flag to easily run tests with the sanitizer. It should be easy to choose whether a given unit or integration test should run with or without <code>libasan</code>. The long-term goal is to transition all tests to run in sanitized mode, but many would currently fail due to memory leaks.
#Create a setup to link inkscape with <code>libasan</code> in the CI pipeline for use in end-to-end tests. After building object files, link two inkscape executables: one with and one without <code>libasan</code>. Create a flag to choose which end-to-end test (e.g., CLI test) should run with the sanitizer (aspirationally, all of them, but not long ago even running <code>inkscape --help</code> leaked memory).
#Migrate some of the existing tests to unit test framework. Do not link all of inkscape just to test a single class or collection of functions.
#Devise a test strategy for the interactions between <code>SPObject</code>s and their XML representations. For each <code>SPObject</code> type, it should be possible to easily write tests that create such object (in isolation or in a test fixture simulating a minimalistic document) from an XML string representation and, likewise, write an XML representation of the object. Unit tests of this kind would characterize and document the properties of XML representations and, with sufficient coverage, can prevent data loss bugs and many undo-related issues.
#Create fixtures for testing <code>SPObject</code> behavior. It should be possible to create an <code>SPObject</code>, perhaps embedding it in a minimalistic document provided by a suitable fixture, and perform specific operations on this object in order to create unit tests for all the different <code>SPObject</code>s.
#Write integration tests for document-level interactions. The goal is to test scenarios where several objects depend on each other: clones, groups, gradients, LPE objects, markers which link to each other by href or another type of reference. Integration tests of this kind (linking the entire libinkscape_base into the test executable) will ensure robust handling of situations such as deletion of dependencies, clipboard operations, undo. When run with the sanitizer, they may catch rare memory corruption bugs.
#Refactor the LPE system. The LPE system dynamically rewrites the d attribute of an SVG path in order to create an artistic effect. As such, each LPE should be easily testable in principle. Migrate existing end-to-end tests of the LPE system and make them unit tests. Assumption: making LPEs individually testable will improve the quality of LPE-related code and offer an opportunity to redesign it.
#Enable test coverage reports in the CI pipeline. This was already done in lib2geom and the extensions repository, so a similar setup should be easy to reproduce.
#Create more rendering tests. The display system should be tested more rigorously in order to prevent rendering regressions.
#Automated action-based tests. We could write more tests that execute a sequence of actions, either on a fresh document or on a pre-existing one. Although this could be done with end-to-end CLI-based tests, it is probably easier to have a C++ test fixture with actions called manually or via their string names.
#Examine the possibility of creating event-injection GUI-tests. If successful, this could save a lot of time currently spent on manual GUI testing.
#Enhance contribution and code review guidelines with testing-related information A careful balance has to be struck beween the imperative of enforcing a sufficient test coverage and allowing for contributions from relatively inexperienced community members who may lack the knowledge of good practices related to testing. Guidelines which help educate contributors, in addition to learning from examples (for instance, tests created as a part of items listed above) will ensure that even new contributors can contribute to the QA goals within Inkscape. 
==Automated testing==
[[File:Test pyramid.png|frame|right|The Test Pyramid illustrates the relative importance and the desired prevalence of tests at different coverage levels.]]Inkscape's CI pipeline contains a number of unit, integration and end-to-end tests. However, we recognise that the overal test coverage is '''very poor''' as of late 2023. One of the main goals of this initiative is to track the test coverage and work on gradually increasing it.

In the context of automated tests, we recall the famous Testing Pyramid (see right). It expresses the principle that tests at unit and component level should be the most prevalent ones, followed by a smaller number of integration tests, and topped off with a relatively lower number of end-to-end tests. Unfortunately, this is not the case today: we have too few unit tests. Manual testing should be limited to UX and usability aspects.

===Why does Inkscape not have enough unit tests===

*Historical reasons: feature development was prioritized and testing was never formally enforced.
*Work on tests and QA topics may be perceived as less newsworthy because it is less visible to the end user.
*Many new developments interact with and depend on legacy code which is hard to split off and mock. Thus, new code is hard to test.
*Insufficient tooling such as automated test coverage reports or custom test fixtures to facilitate test development.
*Varied knowledge level of contributors, some lacking expertise in testing.

===What can be done about it===

*Code review should emphasize the importance of adding unit tests for new functionality and regression tests for bug fixes.
*Quality and maintainability should be viewed as core aspects and as an important part of Inkscape's development.
*Legacy code must be managed carefully, see below.
*Test coverage reports should be introduced along with facilities that make it easy and pleasant to write tests.
*By increasing the number of tests, we can increase the knowledge and awareness of testing techniques in the community – learning from examples.

==Dealing with legacy code ==
According to Michael Feathers, the author of the influential book "Working effectively with legacy code", ''legacy code'' is not defined as "old code", "code written in C" or in general "code that nobody maintains". Instead, legacy code is '''code that is''' '''not testable and not tested.''' We recognise that Inkscape contains a lot of such code.

===The Vicious Cycle of Legacy Code===
The fundamental problem with legacy code is that it's very risky to change it because a small change in one place can have unpredictable and unintended consequences in other places. This has happened many times in Inkscape's history and has led to severe bugs. In an ideal world, the existing code could be first enriched with "characterization tests" that capture its current behaviour, and tests could also be added for the new behaviour. In this way, we could assure that the development works as intended and doesn't break anything. But, according to our definition, legacy code is '''not testable''' so this cannot be done. We don't live in an ideal world!

Thus, we are stuck in a vicious cycle: to make code testable, we need to refactor it in order to make it testable, but refactoring can break things badly unless we have tests, which unfortunately we don't and which cannot be added because the code is not testable.

To break out of this cycle, we need to start small, adding tests to simple and relatively independent pieces of functionality. It is helpful to identify the "seams", which usually correspond to interfaces, along which the program or a system can be natuarally divided into functional pieces. If these pieces are simple enough, they can be made testable. However, even with this approach, a fair bit of mocking may be required to simulate external dependencies, which makes it a tedious task.

===Refactoring and development techniques to increase testability===
A large portion of Inkscape's codebase is made up of code that's very literal, low-level and suffers from a lack of abstraction. Oftentimes, such code was developed as a part of a small contributions without architectural goals, focused only on adding a small missing piece of functionality. As contributors come and go, this leaves behind a patchwork of fairly inconsistent solutions. Nonetheless, many parts of Inkscape have seen some notable refactoring efforts aimed at unifying these patchwork solutions. It is however important that future refactoring efforts take testability considerations into account.

Desigining good interfaces and abstractions is an important goal that should be kept in mind not only during major architectural updates, but also our everyday work. Whenever you work on Inkscape, ask yourself the question: "Does this change make the code I'm working on more or less testable?". Below are some concrete examples of techniques that can help increase testability.

====Extract and mock/override====

*Identify the piece of code that makes the functionality non-testable.
*Move this piece of code to a separate function(s) or a class. Moving code is safer than rewriting it, because the functional logic is kept unchanged.
*In tests, mock the class or function that the problematic code was moved to. This lets you test new functionality independently of the legacy code.
*If you need to extend the functionality provided by the non-testable code, try doing it without touching the untested function, but rather wrap around it or provide an override.

====Decorator pattern====
This design pattern helps extend a legacy class with new functionality. Instead of adding the new functionality directly to the non-testable class (which would make the new functionality non-testable as well), write a wrapper around the legacy class. In the decorator pattern, the decorator class holds an instance of the wrapped class and provides an interface that forwards member function calls to the wrapped object. However, some of the member functions of the wrapper can provide additional functionality or further work on the values obtained from the wrapped object, which makes it possible to add new behaviours. This new functionality can now be tested by mocking the wrapped class in tests.

====Façade transformation====
This technique helps when dealing with huge classes that hold too much data and that have too many member functions, making them complex, difficult to test, and increasing the coupling with other parts of the code. The façade transformation replaces the large class with a façade class which internally holds instances of several smaller classes. These smaller classes need to be designed by identifying the functionally cohesive pieces of the original large class and splitting them up. The member functions of the façade delegate to member function calls on these internal instances, sometimes more than one at a time. This transformation can be repeated if needed, until the classes are small enough that testing them is possible. The advantage of the façade transformation is that the API exposed by the large class is unchanged.

==Guidelines on writing unit tests==

*Create a separate test executable for each class or functional module.
*Write a separate test case for each of the tested behaviours.
*Write a doxygen-style comment above each test case, explaining very briefly what this case is testing.
*In each test case, follow the Arrange-Act-Assert principle:
**Arrange: create and prepare the data and objects needed to perform the tested operation; set up expectations for mock calls;
**Act: run the tested operation;
**Assert: use <code>EXPECT_*</code> and <code>ASSERT_*</code> macros from Google Testing library to check that the behaviour is as expected.
*Remember to test strange and corner cases, invalid input, fallback behaviours.
*If your test needs custom set-up and tear-down, use a custom test fixture and <code>TEST_F</code> macros.
*If your test needs to run on several cases parametrized by input data, consider using a <code>TEST_P</code> fixture.

==Guidelines on writing end-to-end tests==
If you are about to create an end-to-end test, ask yourself first if perhaps a unit test can be written instead. However, in the case of regression tests, it's often good to have end-to-end tests that clearly demonstrate that a bug has been fixed and ensure it is not accidentaly reintroduced. End-to-end tests are also suitable for complex cases involving import and export operations. In many cases (such as display and rendering, utilities, Live Path Effects, SPObject system, anything in lib2geom), unit tests ought to be preferred.

*If you create test files (SVG documents or files in other formats), ensure that the content of the files can be visually inspected.
*If your test file contains both test objects and reference objects, ensure that the relationship between them can be directly inspected visually by a human being in order to confirm that the tested behaviour is indeed correct. You may use existing fixtures such as <code>Inkscape::TestWithSvgObjectPairs</code> for this purpose.
*If you use separete reference files, ensure they can be visually inspected as well.
*Try to make your test focused on the tested behaviour by reducing the number of unrelated elements in your test files.
*Try to make your test robust and independent on implementation details unrelated to the tested behaviour.

2023-12-17T12:34:22Z

S-Rafael: Move to Wiki Attic category

= Nachrichten schreiben und veröffentlichen =

Wir verwenden für den neuen Bereich der Inkscape-Website [http://wordpress.org/ [[WordPress]]]. Jeder darf mitmachen - einfach registrieren und einen Artikelentwurf schreiben. Nach der Überprüfung durch einen Entwickler wird dieser auf der Website veröffentlicht.

Falls du also irgendwelche Neuigkeiten hast, die alle Inkscape-Nutzer interessieren könnten - hab keine Angst und trau dich, einen kurzen Artikel darüber zu schreiben:

# Leg dir einen Account unter http://inkscape.org/wp/wp-register.php an, merk dir deine Daten (Username[[/Passwort]])
# Logge dich unter http://inkscape.org/wp/wp-admin/ ein
# Klick auf den Link "Write" in der Navigation
# Schreib deinen Artikel und speichere ihn anschließend

Dein Artikel wird von einem Programmierer geprüft, bevor er auf der Hauptseite erscheint.

Bitte lies deinen Bericht vor dem Speichern noch einmal durch und bessere Rechtschreib- und Grammatikfehler aus - du ersparst den Entwicklern so sehr viel Zeit.

= Entwickler =

Du bist ein Entwickler? Turnip (turnip at turnipspatch dot com) kann deinen Userstatus erhöhen, dann kannst du auch Artikel in Eigenverantwortung posten.

[[Category:German]]
[[Category:Wiki Attic]]

Quality Assurance Initiative

2023-12-16T20:25:00Z

S-Rafael:

File:Test pyramid.png

2023-12-16T20:22:52Z

S-Rafael:

Test pyramid diagram

2022-06-06T20:09:00Z

S-Rafael: Complete rewrite with status updates as of 2022 and significantly more detail.

This page details work items that need to be completed in order to remove Livarot from Inkscape's code base.

This project requires a substantial amount of work and welcomes all volunteers who would like to contribute
code, help in code review, as well as help test the new functionality at later stages of the development.

== Work items ==

=== Project Path Operations ===
There's an initial implementation of path boolean operations in lib2geom (MSc thesis subject of Krzysztof Kosiński),
but it needs substantially more work before it has all the features and proven reliability needed to fully replace Livarot.

==== Path Intersection Graph ====
The <code>PathIntersectionGraph</code> class underlies all existing boolean operations in lib2geom, implementing the [https://en.wikipedia.org/wiki/Greiner%E2%80%93Hormann_clipping_algorithm Greiner-Hormann algorithm].
Unfortunately, the current implementation is flawed in several ways.
For instance, it cannot handle certain kinds of intersections, e.g., two paths merging and traveling together for some distance.
Furthermore, it's not able to compute the union, intersection or difference of two identical shapes (as of May 2022).

* Write additional unit tests for the <code>PathIntersectionGraph</code> to capture some of the existing breakage; currently being worked on by [https://gitlab.com/S-Rafael @S-Rafael].
* Rework the inclusion classification in the <code>PathIntersectionGraph</code>, a key step of the Greiner-Hormann algorithm. This provides an alternative “geometric” strategy for the classification of crossings and deciding which path portions lie inside the other path-vector. Currently being worked on by [https://gitlab.com/S-Rafael @S-Rafael].
* Write a path uncrossing algorithm. This provides a <code>flatten</code> primitive which removes self-overlaps and self-crossings with the help of <code>PathIntersectionGraph</code>. A path that self-intersects should be cut at the intersection points and replaced by one or several paths that do not have self-intersections. Note that we only need to remove actual transverse self-intersections and not all spurious solutions from the sweepline algorithm. Implicitly, the 2-dimensional shapes in lib2geom are defined by path-vectors using the “even-odd” fill rule. The flattening function converts such a path-vector to one which works with the “non-zero” fill rule, similar to <code>sp_flatten</code> [https://gitlab.com/inkscape/inkscape/-/blob/master/src/path/path-boolop.h#L17]. [[File:Flatten.png|frame|The "flatten" operation replaces a self-intersecting path with one that doesn't cross over itself. The result path, shown on the right, has the same fill region regardless of whether "even-odd" or "nonzero" fill rule is used.]]

* Write functions that implement path cutting (slicing) and division. “Slicing” refers to cutting all paths in a path-vector along all intersection points with another path-vector. “Division” refers to using one path-vector as a “cookie cutter” which divides the other path-vector (the “dough”) into several shapes. [[File:Division.png|frame|The "division" operation is analogous to using a cookie cutter on a piece of dough. Note that the white gaps between the resulting pieces have been thickened for better visibility; in reality, these pieces should fit together perfectly.]]

* Write a function which splits a shape into connected components; this corresponds to <code>split_non_overlapping</code> in Inkscape and should be implemented directly in the <code>PathIntersectionGraph</code>.

* Write even more unit tests to ensure that all this functionality is robust and handles all weird and exotic corner cases. If the “geometric” classification strategy works well, make it the default strategy.

* If possible, remove all exceptions from <code>PathIntersectionGraph</code>.

* Implement overloaded boolean operators <code>|</code>, <code>&</code>, <code>-</code>, <code>^</code> on <code>PathVector</code> operands. This is just a cherry on top of the cake and should be added once the new strategy is robust enough for general use.

* Start migrating the path and boolean operations in Inkscape to the new lib2geom implementation. This will involve rewriting most of the source file [https://gitlab.com/inkscape/inkscape/-/blob/master/src/path/path-boolop.cpp path-boolop.cpp] in Inkscape and eventually deleting it entirely.

* Migrate all Live Path Effects which use boolean operations to the new lib2geom facilities.

* Implement boolean operations on sets of shapes, including nested groups [https://gitlab.com/inkscape/inbox/-/issues/7121]. [[File:Exclusion-on-groups.png|frame|The proposed "exclusion" operation on groups of shapes; based on an illustration by Chris Rogers.]]

* Measure the performance of the new boolean operations and devise performance optimizations; in particular consider cache-friendliness of the code and whether or not <code>boost::ptr_vector</code> is actually a good container for this use case.

=== The Shape Tool ===
The new tool (shape tool/welder tool/shape welder) [https://gitlab.com/inkscape/ux/-/issues/109 was proposed] as an alternative to “shape builder” functionality found in other vector drawing programs.
Developing this functionality was the subject of the 2021 Google Summer of Code project by [https://gitlab.com/osamaahmad Osama Ahmad] under the title “On-canvas interactive boolean operations”.
Nonetheless, the [https://gitlab.com/inkscape/inkscape/-/merge_requests/3357 already-developed UI] requires a stable and convenient engine that can power this tool.

=== Path outliner ===
Path outliner was worked on by Liam but the status of this work is unknown.
The biggest obstacle to a robust path outlining functionality is the unreliability of the lib2geom boolean operations as of May 2022.
Once the boolean operations are robust, path outlining can be developed on this basis, although it still requires some work; the main tasks are listed below.

* Write outlining functions for all curve types used in SVG specification: quadratic and cubic Bézier curves, elliptical arcs. A design requirement is the ability to control the relative error of the outline distance (contact [https://gitlab.com/S-Rafael @S-Rafael] for more details).

* Optionally, provide outlining algorithms for other curve types supported by lib2geom.

* The final implementation should outline paths by outlining the constituent curves and combining the outlines with boolean union. At first glance, this may seem excessively complicated compared to the apparently simple [https://ieeexplore.ieee.org/abstract/document/4055919 Tiller–Hanson method], but is actually required for a general implementation. Note that the Tiller–Hanson algorithm was invented for shapes used in CAD, which are a lot less crazy and irregular than arbitrary paths which lib2geom must support.

* Write unit tests for the path outliner.

* Measure performance and optimize.

=== Crazy libnrtype dependency ===
The text layout library libnrtype uses Livarot for line-breaking text in flow regions. This involves using path outline and boolean operation functionality in Livarot and has been the source of some bugs and headaches. However, once path outlining is available in lib2geom, it will not be very hard to use it to create flow regions with variable padding.

=== Python API ===
All of the new functionality described above should be gradually exposed in the Python API, so that Inkscape's extensions can call lib2geom directly instead of routing their calls through Inkscape. This will enable extension authors to perform advanced path operations directly in their Python code.

=== Streaming outliner ===

[[File:Gnarly.png|thumb|A gnarly, jagged outline created by the Eraser Tool due to the retrograde motion of the ends of the tool's nib.]]
The free-hand drawing tools in Inkscape, such as the Calligraphic and Eraser tools, implement a very primitive (but fast) form of path outlining via Bézier fitting. This outlining method causes some problems such as a gnarly, knotted tool trace when one of the nib extremities experiences retrograde motion (leading to the fitting of Bézier curves with loops) [https://gitlab.com/inkscape/inkscape/-/issues/1124].

A much more robust replacement for use in tools would be a “streaming outliner” which accepts incoming sample points in real time, outlines the incoming segments and appends them to a stored, gradually growing outline of the toolpath. This is a long-term goal, since it would require a more streaming-friendly implementation of the functionality in <code>PathIntersectionGraph</code>. In addition to enabling a substantial improvement on the extremely crufty <code>FreehandBase</code> and <code>CalligraphicTool</code> classes in Inkscape (as of May 2022), it could help improve the performance of the Pencil Tool.

== Discussion ==

[[Category:Developer Discussion]]

File:Exclusion-on-groups.png

2022-06-06T19:51:44Z

S-Rafael:

File:Gnarly.png

2022-06-06T19:48:59Z

S-Rafael:

Illustration of limitations of the original outline method employed by free-hand tools in Inkscape.

File:XOR-groups.png

2022-06-06T19:39:42Z

S-Rafael:

An illustration of the proposed XOR operation on groups of shapes.

File:Division.png

2022-06-06T19:35:52Z

S-Rafael:

An illustration of the "division" operation on paths.

File:Flatten.png

2022-06-06T19:32:57Z

S-Rafael:

Illustration of the "flatten" operation.