|
|
#1 |
|
Addict
![]() ![]() ![]() ![]() ![]() ![]() ![]() ![]() ![]() ![]() ![]() Posts: 292
Karma: 364036
Join Date: Jul 2026
Location: Planet Earth
Device: Kobo Forma
|
Veripublica epub-test-books: small EPUBs for testing EPUB tools
I've started a library of small EPUB files for testing EPUB tools: validators, converters, fixers and reading apps. Each book shows one thing, either a rule from the EPUB or CSS specifications or a defect I have met in real books, and nothing else. When a tool gets a book wrong, you can see exactly what it got wrong.
I made it because I was testing my own tools against shelves of commercial books. They can't be shared, they take a long time to scan, and the one thing you are looking for hides among a thousand others. W3C's EPUB tests already cover reading systems well. These books are mostly for the tools that check or change books, and many of them are broken on purpose. The rule I care about most is where the answer comes from. For every book, I write the expected result from the specification, quoting the sentence, before any tool runs. Then I run epubcheck and epubveri, my own validator, on it and keep their output next to the book. When a tool disagrees with the specification, the book says so, and that includes epubveri. Every book starts as a public issue on GitHub with the question, the clause and the expected result. The discussion happens there, and the issue closes when the book is in. If you think a result is wrong, say so under its issue, or here, and I will carry it over. When I change a result, the release notes say what changed and why, and the old outputs stay as they were, so anyone can see where I was wrong and how it was fixed. Three releases are out. The latest, v0.2.0, has the two templates, one for EPUB 3 and one for EPUB 2, and 22 sets on the EPUB container: damaged ZIP files, the mimetype file, file names, container.xml and its rootfile. Each release is a tag you can pin. The books are ready-made .epub files, listed on one index page with what each should give and what each validator says, and you can download them one by one or all together in a single zip. They are CC BY 4.0, so you can copy them into your own test suite with one line of credit. The container section is not finished, and that is partly why I'm posting now. I have left out every case where the specification and the validators disagree, and listed them in one issue: open questions. Most of them come down to one question: should a book say invalid when the specification says so and no validator reports it? I would rather settle that with people who read the specification closely than on my own. If you have a book that broke your tool, a rule you think nobody checks, or a reading of the specification you disagree with, post it here or open an issue. You don't need to build anything. I'll make the book. https://github.com/veripublica/epub-test-books Last edited by Kayadelenium; 11-08-2026 at 02:13 PM. |
|
|
|
|
|
#2 |
|
Addict
![]() ![]() ![]() ![]() ![]() ![]() ![]() ![]() ![]() ![]() ![]() Posts: 292
Karma: 364036
Join Date: Jul 2026
Location: Planet Earth
Device: Kobo Forma
|
v0.5.0 is out. When I opened this thread there were 22 sets, and now there are 224, plus the two templates.
The container section has grown to 33 sets, with encryption.xml and font obfuscation added. The new sections are the EPUB 3.3 package document (56 sets), navigation document (37), publication resources (31) and content documents (31), and the EPUB 2.0.1 package and NCX (36). Most of the books are broken on purpose, but 36 sets are expected to be valid, so they also catch a tool that reports something the specification allows. Every book is on one index page, with what it should give and what each validator says. The release has them all as downloads, one by one or in a single zip, so there is nothing to build. Nine books now disagree with epubcheck 5.4.0. In five it reports nothing where the specification says invalid, and in four it reports an error where the specification says valid. Each of those books quotes the clause and links the issue I opened on epubcheck. These are my readings of the specification, and they are open for anyone to dispute, including epubcheck's maintainers. No book is marked against epubveri, my own validator, but don't read much into that. Building these sets turned up a long list of gaps in it, and I fixed them before this release. epubcheck hasn't had that chance. So far nobody but me has checked the expected results of the 191 new books, and that is where I could use the most help. If a result looks wrong to you, say so here or under the book's issue. If I change it, the release notes will say what changed and why. The open questions from my first post are still open. The cases the specification calls invalid and no validator reports are still left out. I'm holding them until 15 November, so anyone who reads them differently has time to say so. The cases with no clear rule stay out until W3C answers. Not built yet: fixed layout, EPUB 2 content documents, CSS beyond what EPUB 3.3 itself restricts, and books encrypted with AES. If you would like one of those sooner, or you have a case of your own, tell me and I'll make the book. https://github.com/veripublica/epub-...ses/tag/v0.5.0 |
|
|
|
|
|
#3 |
|
Addict
![]() ![]() ![]() ![]() ![]() ![]() ![]() ![]() ![]() ![]() ![]() Posts: 292
Karma: 364036
Join Date: Jul 2026
Location: Planet Earth
Device: Kobo Forma
|
v0.6.0 is out, with 376 new sets. That makes 600, plus the two templates.
Everything on last time's "not built yet" list is in. There are 72 sets on EPUB 3.3 fixed layout (the rendition properties, the viewport meta tag and its syntax, the initial containing block), 77 on EPUB 2 (OCF 2.0.1 and OPS 2.0.1 content documents), and 74 on CSS, from CSS Syntax 3 encoding and error recovery to selectors and the cascade. AES-encrypted books are in the container section now, next to ZIP64 and obfuscation. The other new sections are media overlays (46) and more content documents (70): dir and bdo, scripting, epub:type and prefixes, RDFa and microdata, switch, trigger and SVG content documents. Every book is on one index page, with what it should give and what each validator says, and the release has them all as downloads. epubcheck 5.4.0 disagrees with 61 of the books. In 24 it reports nothing where the specification says invalid, and in 39 it reports an error where the specification says valid (two books have both). Most of the second kind are CSS that EPUB 3.3 allows but its CSS parser does not know yet, such as nested rules. Each of those books quotes the clause and links the issue I opened on epubcheck. As before, these are my readings, and anyone can dispute them. One of the open questions went to W3C, and the working group discussed it at its meeting on 12 November: an encryption.xml entry for a file that is not in the container. Their answer is that it is an error, and a pull request that says so in the EPUB 3.4 draft has been approved. A second question, whether encryption.xml always needs an EncryptedKey, is open as w3c/epub-specs#3112. No book is marked against epubveri again, but only because I fixed what these sets turned up in it before the release. The expected results of the new books are still checked only by me, so that is where help is most useful. If one looks wrong to you, say so here or under the book's issue. A few cases are still held until 15 November, and the ones with no clear rule stay out until W3C answers; both are listed in the open questions issue. If you have a case you would like to see, tell me and I'll make the book. https://github.com/veripublica/epub-...ses/tag/v0.6.0 |
|
|
|
|
|
#4 |
|
Addict
![]() ![]() ![]() ![]() ![]() ![]() ![]() ![]() ![]() ![]() ![]() Posts: 292
Karma: 364036
Join Date: Jul 2026
Location: Planet Earth
Device: Kobo Forma
|
v0.7.0 is out, with 24 new sets. That makes 624, plus the two templates.
These are mostly the cases I held back until 15 November because neither validator caught them. In the container: a compressed mimetype file, a "version needed to extract" of 63, a file name of 256 bytes, the mimetype file listed in the manifest, a ZIP entry that promises a data descriptor and has none, and 22 bytes slipped inside the mimetype data so that every offset after it is off. In content documents: dir=" rtl" with a leading space, bdo with dir="auto", an img with no alt, and a fixed-layout viewport with a height of 0. For EPUB 2 there are six OPS 2.0.1 rules (an object whose type differs from the manifest, noscript before its script, a style element of type text/plain, align="char", and SVG animation and script) and four OPF 2.0.1 ones. Three of the new books are valid, and they may be the most useful ones for anyone who writes a ZIP reader. In each, the local header of one file disagrees with its central directory entry: on the compression method, on the compressed size, or on the CRC-32. The ZIP specification asks for a corresponding central record, but not for equal fields, so I read them as valid. Readers still differ on them: Info-ZIP's unzip reports a bad CRC on two of them, while Python's zipfile reads all three. Every book is on one index page, with what it should give and what each validator says, and the release has them all as downloads. epubcheck 5.4.0 now disagrees with 81 of the books. In 44 it reports nothing where the specification says invalid, and in 39 it reports an error where the specification says valid (two books have both). The new misses are in two issues I opened today, w3c/epubcheck#1779 (the EPUB 3 container and ZIP cases) and #1780 (the OPS 2.0.1 cases). No book is marked against epubveri, but only because it was fixed for these cases before the release. Its output on the 602 older books did not change. One case is still held on purpose: EPUB 3.4 drops the "www" from the structure vocabulary's prefix URL, and that book waits until 3.4 is a Recommendation. The cases with no clear rule stay in the open questions issue. As before, the expected results are my readings of the specifications, and anyone can dispute them. If one looks wrong to you, say so here or under the book's issue. If you have a case you would like to see, tell me and I'll make the book. https://github.com/veripublica/epub-...ses/tag/v0.7.0 |
|
|
|
|
|
#5 |
|
Addict
![]() ![]() ![]() ![]() ![]() ![]() ![]() ![]() ![]() ![]() ![]() Posts: 292
Karma: 364036
Join Date: Jul 2026
Location: Planet Earth
Device: Kobo Forma
|
v0.8.0 is out, with 48 new sets. That makes 672, plus the two templates.
The largest group is EPUB 2: 21 sets on ops:switch from OPS 2.0.1 section 2.6.3.1. They cover where a switch may stand, what its case and default must hold, and whether the content of the default fits where the switch is, in body, in a paragraph, in lists, in a definition list and in tables. 11 of them are valid and 10 invalid, and both validators agree on all of them. Then 15 CSS sets, which styloria asked for: pseudo-classes after a pseudo-element (Selectors 4), a second shadow part or a structural pseudo-class after a shadow part (CSS Pseudo-Elements 4), four style sheets whose last block is still open at the end of the file, and ui-serif as an @font-face family name. All of them are valid EPUB. The third group answers a question I asked the EPUB working group in w3c/epub-specs#3115: what it means that an EPUB style sheet "MUST NOT include the direction property". The answer was that the property must be declared, that is, still there after the CSS parser has read the sheet, and that a style attribute counts as a style sheet. So a direction declaration that CSS throws away is valid: one with a value direction does not take, one inside an unknown at-rule, one in a rule with an invalid selector or an undeclared namespace prefix, one after a stray closing brace. Using direction only as an @supports condition is valid too. But direction or unicode-bidi in a style attribute is invalid, inline SVG included. Each book's README says why. The last new book is an AES-encrypted content document whose encryption.xml has no EncryptedKey. It is valid: w3c/epub-specs#3112 made EncryptedKey optional and called it a fix. That change is in the EPUB 3.4 draft, and I apply it to EPUB 3.3 too. Every book is on one index page, with what it should give and what each validator says, and the release has them all as downloads. Every book's epubveri output now comes from epubveri 0.47.0. Three older books get an extra advisory message from it, and none changes its verdict. epubcheck 5.4.0 now disagrees with 92 of the books. In 45 it reports nothing where the specification says invalid, and in 49 it reports an error where the specification says valid (two books have both). For the new direction books I opened w3c/epubcheck#1781. epubveri reports an error on the six where CSS throws the declaration away, so it is marked too (it had no marks in v0.7.0), and it knows. The cases with no clear rule stay in the open questions issue. As before, the expected results are my readings of the specifications, and anyone can dispute them. If one looks wrong to you, say so here or under the book's issue. If you have a case you would like to see, tell me and I'll make the book. https://github.com/veripublica/epub-...ses/tag/v0.8.0 |
|
|
|
![]() |
| Tags |
| epub, epubcheck, epubveri, test files, validation |
|
Similar Threads
|
||||
| Thread | Thread Starter | Forum | Replies | Last Post |
| EPUB reader testing | swepub | ePub | 16 | 05-27-2024 10:10 AM |
| keeping small images small in an epub | krommenaas | Editor | 3 | 01-17-2021 05:17 AM |
| EPUB testing most features of EPUB | crankypants | ePub | 7 | 01-26-2016 03:22 PM |
| Testing approach for EPub | kalees | ePub | 7 | 01-21-2014 01:47 PM |
| Help Merging Multiple Small Epubs into One Large Epub | kazbates | Workshop | 14 | 09-15-2011 03:18 AM |