Skip to content

Commit 9d1207d

Browse files
committed
docs: the README front page shows the tool and counts it right
The front page had to do two jobs it was not doing: make a visitor want the download, and be true. It is now ordered badges, one paragraph, the star ask, what it can do, two moving pictures, then the table of contents. Measured before writing, because the README is the shop window: * All five badge endpoints answer, with real values - CI passing, release v0.2.0, downloads 82, GPLv3, platform. The green Download badge and the Go badge came off, and the three platform badges lost their links because a platform is a fact and not a place to go. * Anchors come from GitHub's own renderer, read back from this repository rather than worked out from the heading text. That found a trap worth keeping: an emoji carrying a variation selector leaves the selector behind in the slug, so "Commands" answers to an anchor beginning with an invisible U+FE0F while "Formats it generates" answers to a plain hyphen. A link written the way it looks on screen would be dead and would look right. Nineteen of the twenty entries are confirmed against that render. Four sentences said things that stopped being true. The tool registers twenty one formats, the intro claimed twenty and the feature table said twenty. TIFF shipped and the question about what comes next still listed it. The manifest sample quoted version 0.1.0. And the first sentence ended with two full stops. The feature table is gone rather than duplicated: the same eight rows read better as a list, and four more went in that the table never carried - the boundary set, ten thousand files at once, an archive with real contents, and per format settings. Every one of them is something the seven browser based generators measured in August do not do. window.png stays in the tree. The README no longer shows it, but the website does, and a guard compares the two copies byte for byte.
1 parent db0b2ab commit 9d1207d

3 files changed

Lines changed: 73 additions & 32 deletions

File tree

‎.github/star-the-repo.gif‎

29.3 KB
Loading

‎.github/tfg-in-work.gif‎

1.09 MB
Loading

‎README.md‎

Lines changed: 73 additions & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -1,26 +1,80 @@
1-
# Testing Files Generator
1+
# Testing Files Generator - make real test files at any exact size
22

3-
**Generate test files for QA, and know how the system under test should react to them.**. A free, open source tool that creates **real test files** - PDF, PNG, JPG, ZIP, DOCX, XLSX and fourteen more - at **any exact size you ask for**. It also writes down what your application should do with each one. Command line and desktop app, fully offline, on Windows, macOS and Linux.
4-
5-
[![Download](https://img.shields.io/github/v/release/donislawdev/TestingFilesGenerator?label=download&color=2ea043&logo=github&logoColor=white)](https://github.com/donislawdev/TestingFilesGenerator/releases/latest)
63
[![CI](https://github.com/donislawdev/TestingFilesGenerator/actions/workflows/ci.yml/badge.svg)](https://github.com/donislawdev/TestingFilesGenerator/actions/workflows/ci.yml)
7-
[![Licence](https://img.shields.io/badge/licence-GPL--3.0-A42E2B?logo=gnu&logoColor=white)](LICENSE)
8-
[![Go](https://img.shields.io/badge/Go-1.26%2B-00ADD8?logo=go&logoColor=white)](https://go.dev)
9-
10-
[![Windows](https://img.shields.io/badge/Windows-0078D6?logo=windows&logoColor=white)](https://github.com/donislawdev/TestingFilesGenerator/releases/latest)
11-
[![macOS](https://img.shields.io/badge/macOS-000000?logo=apple&logoColor=white)](https://github.com/donislawdev/TestingFilesGenerator/releases/latest)
12-
[![Linux](https://img.shields.io/badge/Linux-FCC624?logo=linux&logoColor=black)](https://github.com/donislawdev/TestingFilesGenerator/releases/latest)
13-
14-
15-
16-
⭐ **If it saved you time, leave a star.** That is how the next tester who needs it finds out it
17-
exists.
18-
19-
![The desktop window of Testing Files Generator, set up to write a batch of test files](.github/window.png)
4+
[![Latest release](https://img.shields.io/github/v/release/donislawdev/TestingFilesGenerator?sort=semver)](https://github.com/donislawdev/TestingFilesGenerator/releases/latest)
5+
[![Downloads](https://img.shields.io/github/downloads/donislawdev/TestingFilesGenerator/total)](https://github.com/donislawdev/TestingFilesGenerator/releases)
6+
[![License: GPLv3](https://img.shields.io/badge/License-GPLv3-blue.svg)](LICENSE)
7+
![Platform: Windows](https://img.shields.io/badge/platform-Windows-0078D6)
8+
![Platform: Linux](https://img.shields.io/badge/platform-Linux-FCC624)
9+
![Platform: macOS](https://img.shields.io/badge/platform-macOS-000000)
10+
11+
Testing Files Generator is a tool for QA engineers and developers who need real
12+
files to test against - an upload form, a parser, anything that takes a file and
13+
has an opinion about it. You pick one of its 21 formats and the size you want,
14+
and you get **exactly that**: ask for a 10 MB PDF and you get a PDF that a reader
15+
will open, at 10 MB to the byte. Every run also leaves a manifest saying **what
16+
your system should do with each file**, which is the part other generators leave
17+
to you. It runs from a desktop window or a command line built for CI, never
18+
touches the network, and works on Windows, macOS and Linux.
19+
20+
⭐ **If it saved you time, leave a star.** That is how the next tester who
21+
needs it finds out it exists.
22+
23+
## ⚡ What it can do
24+
25+
- **Hit an exact size, to the byte** - ask for 10485761 bytes and get exactly
26+
that, never a silently rounded file.
27+
- **Write 21 real formats** - a generated PNG opens in an image viewer, a DOCX
28+
opens in Word, a ZIP extracts. Not padded zeros with an extension.
29+
- **Say what should happen to each file** - the manifest carries an expected
30+
outcome, so your test reads the assertion instead of you writing it out.
31+
- **Repeat itself byte for byte** - same recipe and seed, same bytes, on any
32+
machine. Commit a small recipe instead of large binary fixtures.
33+
- **Build a boundary set in one command** - one byte under a limit, the limit
34+
itself, one byte over. That is where off by one errors live.
35+
- **Produce ten thousand files at once** - one command, one manifest, and sizes
36+
drawn from the seed.
37+
- **Fill an archive for real** - a ZIP that holds 200 documents, not a stub with
38+
the right extension.
39+
- **Take settings per format** - image dimensions, JPEG quality, PDF pages,
40+
spreadsheet rows and columns.
41+
- **Fit into CI** - an exit code for every ending, machine readable output, and
42+
nothing on standard output when a run fails.
43+
- **Clean up after itself** - `verify` tells you nothing moved, `cleanup`
44+
removes exactly what it wrote and nothing else.
45+
- **Work completely offline** - no account, no cloud, no telemetry, no update
46+
check. The command line binary has no network stack compiled into it at all.
47+
- **Cost nothing and stay out of your way** - GPL-3.0, and the files you
48+
generate are yours with no strings attached.
49+
50+
![The desktop window of Testing Files Generator building a set of files around an upload limit, and the files appearing in a folder as they are written](.github/tfg-in-work.gif)
51+
52+
![The Star button at the top of this page, with a cursor pressing it](.github/star-the-repo.gif)
53+
54+
## 🧭 Table of contents
2055

2156
This README is also the manual. The short version is above the line, the full
2257
reference is below it.
2358

59+
- [What it can do](#-what-it-can-do)
60+
- [Formats it generates](#-formats-it-generates)
61+
- [The problem it solves](#-the-problem-it-solves)
62+
- [What makes it different](#-what-makes-it-different)
63+
- [Install](#-install)
64+
- [Quick start](#-quick-start)
65+
- [Reference](#reference)
66+
- [Commands](#️-commands)
67+
- [Recipes](#-recipes)
68+
- [Formats in detail](#-formats-in-detail)
69+
- [The manifest](#-the-manifest)
70+
- [Presets](#-presets)
71+
- [The desktop window](#️-the-desktop-window)
72+
- [Using it in CI](#️-using-it-in-ci)
73+
- [Questions](#-questions)
74+
- [Where this is](#-where-this-is)
75+
- [Everything inside a generated file is made up](#-everything-inside-a-generated-file-is-made-up)
76+
- [Licence](#-licence)
77+
2478
## 📁 Formats it generates
2579

2680
Twenty one, and every one is a **real file of that format** - it opens in the
@@ -104,19 +158,6 @@ And where the right answer genuinely depends on your own policy, the manifest
104158
says `unspecified` instead of inventing one. A generator that guesses produces
105159
false failures, and a suite that cries wolf gets switched off.
106160

107-
## ✨ Features
108-
109-
| | |
110-
|---|---|
111-
| 🎯 **Exact size, to the byte** | Ask for 10485761 bytes and get exactly that. Never a silently rounded file. |
112-
| 📄 **20 real formats** | Not padded zeros with an extension. A generated PNG opens in an image viewer, a DOCX opens in Word, a ZIP extracts. |
113-
| 🧾 **A manifest that is a test oracle** | Path, size, SHA-256, format, seed, tool version - and what your system should do with the file. |
114-
| 🔁 **Reproducible** | Same recipe and seed, same bytes, on any machine. Commit a small recipe instead of large binary fixtures. |
115-
| 🖥️ **Two interfaces, one engine** | A command line built for CI, and a desktop window for exploratory testing. Neither is a cut down version of the other. |
116-
| 🔌 **Completely offline** | No account, no cloud, no telemetry, no update checks. The command line binary has no network stack compiled into it at all. |
117-
| 🧹 **Cleans up after itself** | `verify` tells you nothing moved, `cleanup` removes exactly what was written and nothing else. |
118-
| 🆓 **Free and open source** | GPL-3.0. The files you generate are yours, with no strings attached. |
119-
120161
## 📦 Install
121162

122163
**Download a binary.** Take the archive for your system from the
@@ -441,7 +482,7 @@ interrupted. One entry per file:
441482
```json
442483
{
443484
"manifest_version": "1.0",
444-
"tool": { "name": "testing-files-generator", "version": "0.1.0" },
485+
"tool": { "name": "testing-files-generator", "version": "0.2.0" },
445486
"run": {
446487
"id": "run_b359aa8d94",
447488
"seed": 0,
@@ -619,7 +660,7 @@ a valid one of its format.
619660

620661
### Which formats are coming next?
621662

622-
`7z`, `tiff`, `webp`, `mp3` and `mp4`.
663+
`7z`, `webp`, `mp3` and `mp4`.
623664

624665
## 🚧 Where this is
625666

0 commit comments

Comments
 (0)