Dokumentace

Jaké příkazy existují?

Každý dělá jednu věc:

tfg generate    vytvořit soubory z receptu nebo z přepínačů
tfg validate    zkontrolovat recept a nic nezapisovat
tfg verify      zkontrolovat adresář proti manifestu
tfg cleanup     odstranit soubory, které manifest uvádí
tfg recipe fmt  vypsat recept v ustáleném tvaru
tfg preset      sestavit sadu souborů z pojmenované testovací otázky
tfg formats     vypsat formáty, které tato verze podporuje
tfg damage      vypsat způsoby, jak tato verze umí soubor schválně poškodit
tfg tool        drobné pomůcky pro soubory, které už máte
tfg version     vypsat verzi nástroje
tfg license     vypsat licenci a co znamená pro generované soubory

Jak vygeneruji jeden soubor přesné velikosti?

Uveďte formát, velikost a kam soubor půjde. Velikosti se počítají po 1024, takže 2mb je 2097152 bajtů. Funguje i prostý počet bajtů, takže --size 10485761 žádá přesně tolik.

tfg generate --format png --size 2mb --out ./out

Užitečné přepínače příkazu generate:

Jak vytvořím soubor, který je záměrně rozbitý?

Každý jiný soubor, který tento nástroj zapíše, je správný z konstrukce, což odpovídá na dvě ze tří otázek, které klade validátor nahrávání. --damage odpovídá na třetí - zda se soubor vůbec otevře. Soubor se vytvoří normálně a pak se rozbije, takže má stále velikost, o kterou jste požádali.

tfg generate --format png --size 2mb --damage zero-head --out ./out
tfg generate --format png --size 2mb --damage zero-head:bytes=16 --out ./out

Nastavení se zadávají za dvojtečku. Přepínač se opakuje a pořadí, v jakém je napíšete, je pořadí, v jakém se uplatní. tfg damage vypíše, co tato verze umí a co která varianta přijímá.

V receptu je klíč seznam, a to názvů nebo nastavení:

targets:
  - id: broken
    format: png
    count: 5
    size: 2mb
    damage:
      - zero-head
      - type: zero-head
        bytes: 16

Poškozený soubor dostane v manifestu expected: reject a vedle toho zaznamenané poškození. Dvě věci jsou odmítnuty dříve, než se cokoli zapíše, protože každá by jinak dala na disk soubor, který manifest popisuje špatně:

• soubor menší, než poškození potřebuje, protože by vyšel beze změny
• expected: accept vedle poškození, protože nic by to nemohlo splnit. Napište sanitize, pokud má testovaný systém soubor opravit, nebo unspecified, pokud je to právě ta otázka, kterou kladete

Třetí se předem zjistit nedá. Pokud se poškození provede a nepohne žádným bajtem, soubor se zahodí místo zapsání - běh pokračuje, řekne, o který soubor šlo, a skončí s částečným návratovým kódem.

Krok za krokem, s testem, který čte manifest: jak vytvořit poškozený soubor pro testy.

Jak vypadá recept?

Recept je soubor YAML popisující celý běh. Commitujte ho vedle testů a fixtures přestanou být binárkami ve vašem repozitáři - kdokoli je může bajt po bajtu znovu sestavit ze souboru o několika stovkách znaků.

# fixtures.yaml
version: 1
seed: 7741

defaults:
  label: true

targets:
  - id: invoices
    format: pdf
    count: 25
    size: 300kb
    name: invoice_{index:04}.pdf
    properties:
      pages: 3
      page_size: a4
    expected: accept

  - id: over_the_limit
    format: png
    count: 2
    size: 12mb
    expected:
      outcome: reject
      reason: size_limit

  - id: bundle
    format: zip
    contains:
      - format: txt
        count: 200
        size: 4kb

output:
  dir: ./fixtures
  manifest: manifest.json

tfg validate fixtures.yaml
tfg generate fixtures.yaml

Každý target potřebuje přesně jeden z klíčů size, size-range, boundary nebo contains. Dva jsou chyba a žádný také. Neplatný recept nezapíše žádné soubory a nahlásí všechny problémy najednou, ne jen první, každý s názvem nastavení, kterého se týká.

Jak deklaruji, co má můj systém se souborem udělat?

Krátká forma, když stačí výsledek, dlouhá forma, když záleží na důvodu:

expected: accept

expected:
  outcome: reject
  reason: size_limit

Výsledky jsou accept, reject, sanitize a unspecified. Důvody tvoří uzavřený seznam, aby podle nich mohl report seskupovat: content_malformed, count_limit, dimensions_limit, duplicate, encoding_invalid, extension_rule, filename_invalid, filename_too_long, filename_traversal, malware_signature, mime_mismatch, nesting_depth, none, size_limit a size_zero.

Důvod pojmenovává pravidlo, o které jde, ne verdikt. Proto může stejný důvod stát pod oběma výsledky - soubor o bajt pod limitem je accept a pravidlo, o které jde, je stále size_limit.

Co obsahuje manifest?

Zapisuje se vedle souborů na konci každého běhu, včetně přerušeného. Jedna položka na soubor:

{
  "manifest_version": "1.0",
  "tool": { "name": "testing-files-generator", "version": "0.4.0" },
  "run": {
    "id": "run_b359aa8d94",
    "seed": 0,
    "command": "tfg generate --format png --size 2mb --out ./out",
    "platform": { "os": "windows", "arch": "amd64" },
    "complete": true
  },
  "summary": {
    "file_count": 1,
    "total_bytes": 2097152,
    "by_format": { "png": 1 },
    "by_expected": { "unspecified": 1 }
  },
  "files": [
    {
      "path": "files_0001.png",
      "bytes": 2097152,
      "format": "png",
      "fidelity": "full",
      "determinism": "byte",
      "seed": "8dc2d18c",
      "hashes": { "sha256": "1a1f7c..." },
      "properties": { "width": 640, "height": 480 },
      "expected": {
        "outcome": "unspecified",
        "detail": "No expectation was declared for this file.",
        "confidence": "policy_dependent"
      }
    }
  ]
}

recipe_hash se přidá, když běh pochází z receptu, a preset s overrides, když pochází z předvolby, takže manifest lze vždy dohledat k tomu, co ho vytvořilo.

Každá položka nese také target_id, id targetu v receptu, který soubor vytvořil, a summary.by_target počítá soubory, ke kterým každý target dospěl. Recept s více targety lze tak kontrolovat target po targetu, aniž by se četly názvy souborů.

Co je předvolba?

Hotová sada souborů, která odpovídá na běžnou testovací otázku, abyste sadu nemuseli navrhovat sami. Předvolby jsou pod povrchem obyčejné recepty a eject recept vypíše, takže ho můžete odtud upravit. Každá předvolba má vlastní stránku s tím, co obvykle najde, co je v sadě a jaké nastavení přijímá.

• Prázdné a minimální

  Projde platný soubor tak malý, jak formát dovolí?

  empty-and-minimal

• Zacházení s názvy souborů

  Uloží, zobrazí a vrátí můj systém název souboru, který nečekal?

  filename-handling

• Hranice velikosti

  Je limit velikosti vynucován přesně tam, kde je deklarován?

  size-boundaries

• Import tabulek

  Přežije můj import tabulek to, co exportují skutečné nástroje?

  tabular-import

• Kódování textu

  Ví moje čtečka, v jakém kódování soubor je, nebo hádá?

  text-encoding

• Validace nahrávání

  Přijme můj formulář pro nahrávání to, co má, a zbytek odmítne?

  upload-validation

tfg preset list
tfg preset show size-boundaries
tfg generate --preset size-boundaries --limit 10mb --out ./edges
tfg preset eject size-boundaries > my.yaml

show vám řekne, kolik by sada stála, než ji sestavíte, a otevřeně řekne, když je číslo naším zástupným údajem, a ne vaším limitem.

Co znamenají návratové kódy?

Každý konec má svůj kód, strojově čitelný výstup jde na standardní výstup a neúspěšný běh tam nevypíše nic. Tabulka je zmrazená smlouva - změna významu kódu vyžaduje novou hlavní verzi.

- name: build the fixtures
  run: tfg generate fixtures.yaml --out ./fixtures

- name: run the tests
  run: pytest tests/

- name: nothing moved
  run: tfg verify ./fixtures/manifest.json

Běh zastavený pomocí Ctrl+C po sobě stále zanechá manifest a nikdy nenechá napůl zapsaný soubor, takže zrušenou úlohu může následující stále uklidit.

Hotová workflow pro GitHub Actions a GitLab CI: jak generovat testovací soubory v CI pipeline.

Existuje desktopové okno?

Ano, stejný motor s oknem navrch, pro testování, které se neskriptuje. Není to osekaná verze: test porovnává obě rozhraní schopnost po schopnosti a cokoli, co umí jen jedno z nich, musí být deklarováno a zdůvodněno, ne tiše se rozcházet.

Obrazovky jsou jedna dávka, předvolby, více dávek najednou a O aplikaci. Ukáže, kolik by běh stál, než cokoli zapíše, hlásí průběh a lze ho zrušit uprostřed, aniž by zanechal napůl zapsaný soubor. Soubor receptu zatím neotevře - recepty jsou zatím záležitostí příkazového řádku a okno sestavuje své dávky ve formuláři.