Skip to content

TESTING.md

Latest commit

 

History

History
265 lines (183 loc) · 9.89 KB

TESTING.md

File metadata and controls

265 lines (183 loc) · 9.89 KB
Raw

Testing and Reporting

Whatever problems you experience with Papers, please test against a current flatpak version, as installed from Flathub or the GNOME Nightly Repository. If you can reproduce with these installs, check out our testing guidlines below and file an issue.

Otherwise Papers itself is most likely not at fault and you should report to your distribution's

Bug Trackers

Help us to improve and extend this list!

Testing

should be done on a current Development version, which we assume here. The install is quite easy through flatpak. To test the current main Development version, you will want to use the

Nightly Repository

The advantage is, that you can stay on the Nightly Repository and Papers will be updated therefrom, whenever you run flatpak update from a terminal. You can add the Nightly Repository via

flatpak remote-add --user --if-not-exists gnome-nightly https://nightly.gnome.org/gnome-nightly.flatpakrepo

and install the newest Development version of Papers via

flatpak install --user gnome-nightly org.gnome.Papers.Devel

Here some additional information, if you wish to test a

Specific Pipeline

To test other concurrent Development versions of Papers, head over to Papers' pipelines, download from the dropdown on the right the correct flatpak, unzip the downloaded file and install via

flatpak install --user org.gnome.Papers.Devel.flatpak

and confirm the dialog to authorize. To uninstall, just run

flatpak uninstall --user org.gnome.Papers.Devel

and don't forget to clean up the files!

Reporting

If you wish to report an issue, please do so on a latest Development version and mention the exact version. To that purpose run from a terminal

flatpak info --user org.gnome.Papers.Devel

and include the OUTPUT as Information

Preferrably insert the OUTPUT into a collapsible section, which you can create in Gitlab's text field from the comment menu atop in plain text mode or via

<details><summary>Information</summary>

```
OUTPUT
```

</details>

Note the spacing and three ticks before and after OUTPUT. In this way the format of the OUTPUT is preserved, yet collapsible to not clutter the issue tracker.

Papers Crashes

To address crashes some more information is useful to debug the problem. Here we assume, that you have a current Development version installed as --user, as explained above.

Additional Packages

To add the necessary packages for debugging, from a terminal run

flatpak install --user gnome-nightly org.gnome.Sdk

and

flatpak install --user gnome-nightly org.gnome.Sdk.Debug

and

flatpak install --user gnome-nightly org.gnome.Papers.Devel.Debug

Be advised, that these packages consume more 4GB disk space, so you may want to remove them, after having created a debug log file.

Creating a Debug Log File

Now, to actually debug Papers, run

flatpak run --command=sh --devel --user org.gnome.Papers.Devel

then

gdb /app/bin/papers

and finally

run

Now Papers should start. Try to reproduce the crash or, if necessary, close Papers. In the terminal then type

bt full

and copy the OUTPUT in a relevant Gitlab issue, again preferrably into a collapsible section, see above.

Rendering Issues

If a pdf file renders incorrectly, e.g. you observe missing or blurry fonts, the culprit might be Poppler, a library Papers relies on. To test, whether that's the case, copy a problematic FILENAME.pdf pdf file into your Download folder and from a terminal run

cd && cd ~/Downloads

and

mkdir -p ~/Downloads/pdftocairo_test && flatpak run --filesystem=~/Downloads --command=pdftocairo org.gnome.Papers.Devel FILENAME.pdf -png ~/Downloads/pdftocairo_test/test.png`

After completion you will find a folder, named pdftocairo_test in your Download folder, containing the single pages of FILENAME.pdf as png image files. Using your image viewer of choice check, whether the rendering issue is still observable with these image files.

Digital Signatures

In order to avoid the exposure of personal data and to make the inspection and analysis of the signed PDF document easier, please observe the three following steps.

Generate a Self-Signed Certificate

Create your own self-signed certificate with OpenSSL, with the following three commands:

  1. The first command generates both private key and public key within the public certificate (all automatic, without any user input).
  2. The second command merges both files single into a passwordless file
  3. The third command prompts the user to remove the intermediate files (not needed anymore after full certificate generation):

We first generate both the private key and the public certificate:

openssl req -x509 -newkey rsa -keyout key.pem -out cert.pem -noenc -days 1500 -subj "/CN=Papers (for testing purposes only [RSA 2048])"

Then merge both files into a single certificate (without password):

openssl pkcs12 -export -out  certificate_testing_papers-rsa.pfx -inkey key.pem -in cert.pem -passout pass:

Third, consider removing the intermediate files

rm -i key.pem cert.pem

Since this certificate is only useful for testing signatures and it’s intended to be used with Papers, it contains no password and generation is totally automatic. Only after successful certificate generation, you will be prompted to remove the intermediate files.

Only use the certificate for testing signatures in Papers. In any case, self-signed certificates cannot have any legal value for end users.

Each generated certificate expires after 1500 days (roughly four years). If you have a reason for longer or shorter times, replace the value of the -days option from the first command.

If you prefer to generate an ECDSA, there are also three required OpenSSL commands.

First, generate both private key and public certificate with public key:

openssl req -x509 -nodes -days 1500 -newkey ec -noenc -pkeyopt ec_paramgen_curve:prime256v1 -keyout key.pem -out cert.pem -subj "/CN=Papers (for testing purposes only [ECDSA])"

Then merge both files into a single certificate without password:

openssl pkcs12 -export -out  certificate_testing_papers-ecdsa.pfx -inkey key.pem -in cert.pem -passout pass:

Third, consider removing both intermediate files (useless after successful certificate generation):

rm -i key.pem cert.pem

Of course, nothing prevents that you generate both RSA and ECDSA certificates, import and use them to test.

Import the certificate(s) in Firefox

To import the generated certificate(s) in Firefox:

  1. In a terminal, run firefox about:preferences (or go to about:preferences in Firefox).

  2. Type certificates in the search field Find in Settings and click on the first button View Certificates….

  3. Select the first tab Your Certificates and then click on the button below Import….

  4. Navigate to reach certificate_testing_papers-rsa.pfx (or certificate_testing_papers-ecdsa.pfx) and double-click on it.

  5. Press the Sign in button directly, since no certificate has any password at all.

Sign a Blank PDF Document

Use a blank PDF document1 as signing document.

This has much fewer objects (no visible contents other than a single empty page).

This also makes easier to read, inspect and analyze the signed PDF document.

Reverting the Changes

If you wish to undo the several debugging installations, from a terminal run

flatpak uninstall --user org.gnome.Sdk

and

flatpak uninstall --user org.gnome.Sdk.Debug

and

flatpak uninstall --user org.gnome.Papers.Devel.Debug

and

flatpak uninstall --user org.gnome.Papers.Devel

and

flatpak remote-delete gnome-nightly

Footnotes

  1. Blank PDF document generated with ConTeXt (TeX macro package) from the following source:

    \starttext
\startTEXpage[offset=10cm, pagestate=start]
\null
\stopTEXpage
\stoptext

    Of course, it can be regenerated with the online version at https://www.context-on-web.eu/.

    Alternatively, you may use the ImageMagick tool:

    convert xc:none -page A4 a.pdf
    ↩