Dokumentasi

Perintah apa saja yang ada?

Masing-masing melakukan satu hal:

tfg generate    menghasilkan file, dari resep atau dari opsi
tfg validate    memeriksa resep tanpa menulis apa pun
tfg verify      memeriksa direktori terhadap manifes
tfg cleanup     menghapus file yang tercantum dalam manifes
tfg recipe fmt  mencetak resep dalam bentuk bakunya
tfg preset      membuat set file dari pertanyaan pengujian bernama
tfg formats     mendaftar format yang didukung build ini
tfg damage      mendaftar cara build ini dapat merusak file dengan sengaja
tfg tool        alat kecil untuk file yang sudah Anda miliki
tfg version     mencetak versi alat
tfg license     mencetak lisensi dan artinya bagi file yang dihasilkan

Bagaimana cara membuat satu file dengan ukuran tepat?

Sebutkan format, ukuran, dan tujuannya. Ukuran dihitung dalam kelipatan 1024, jadi 2mb adalah 2097152 byte. Jumlah byte biasa juga bisa, jadi --size 10485761 meminta persis sebanyak itu.

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

Opsi yang berguna pada generate:

Bagaimana membuat file yang sengaja dirusak?

Setiap file lain yang ditulis alat ini benar menurut konstruksinya, yang menjawab dua dari tiga pertanyaan yang diajukan validator unggahan. --damage menjawab yang ketiga - apakah file itu dapat dibuka sama sekali. File dibuat secara normal lalu dirusak, sehingga ukurannya tetap seperti yang Anda minta.

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

Pengaturan ditulis setelah titik dua. Opsinya dapat diulang, dan urutan penulisannya adalah urutan penerapannya. tfg damage mendaftar apa yang bisa dilakukan build ini dan apa yang diterima masing-masing.

Dalam resep, kuncinya adalah daftar, berisi nama atau pengaturan:

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

File yang dirusak mendapat expected: reject di manifes, dengan kerusakan dicatat di sampingnya. Dua hal ditolak sebelum apa pun ditulis, karena masing-masing akan menaruh file di disk yang digambarkan manifes secara keliru:

• file yang lebih kecil dari yang dibutuhkan kerusakan, karena akan keluar tanpa perubahan
• expected: accept di samping kerusakan, karena tidak ada yang dapat memenuhinya. Tulis sanitize bila sistem yang diuji dimaksudkan memperbaiki file, atau unspecified bila itulah pertanyaan yang Anda ajukan

Yang ketiga tidak dapat diketahui sebelumnya. Bila suatu kerusakan berjalan dan tidak menggeser satu byte pun, file itu dibuang alih-alih ditulis - run berlanjut, menyebut file mana itu, dan berakhir dengan kode keluar parsial.

Langkah demi langkah, dengan tes yang membaca manifes: cara membuat file rusak untuk pengujian.

Seperti apa bentuk sebuah resep?

Resep adalah file YAML yang menggambarkan satu run utuh. Commit di samping pengujian Anda dan fixture berhenti menjadi biner di repositori Anda - siapa pun dapat membangunnya kembali, byte demi byte, dari file berisi beberapa ratus karakter.

# 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

Setiap target memerlukan tepat satu dari size, size-range, boundary, atau contains. Dua adalah galat dan tidak ada juga galat. Resep yang tidak valid menulis tidak ada file sama sekali dan melaporkan semua masalah sekaligus, bukan hanya yang pertama, masing-masing menyebut pengaturan yang dimaksud.

Bagaimana menyatakan apa yang harus dilakukan sistem saya terhadap sebuah file?

Bentuk pendek bila hasilnya sudah cukup, bentuk panjang bila alasannya penting:

expected: accept

expected:
  outcome: reject
  reason: size_limit

Hasilnya adalah accept, reject, sanitize, dan unspecified. Alasannya adalah daftar tertutup agar laporan dapat mengelompokkan berdasarkan itu: 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, dan size_zero.

Alasan menyebut aturan yang berlaku, bukan putusannya. Itulah sebabnya alasan yang sama dapat berada di bawah kedua hasil - file satu byte di bawah batas adalah accept, dan aturan yang dimaksud tetap size_limit.

Apa isi manifes?

Manifes ditulis di samping file pada akhir setiap run, termasuk run yang terhenti. Satu entri per file:

{
  "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 ditambahkan bila run berasal dari resep, dan preset dengan overrides bila berasal dari preset, sehingga manifes selalu dapat ditelusuri ke apa yang menghasilkannya.

Setiap entri juga membawa target_id, id target dalam resep yang menghasilkan file, dan summary.by_target menghitung file yang dihasilkan tiap target. Resep dengan beberapa target dapat diperiksa target demi target tanpa membaca nama file.

Apa itu preset?

Set file siap pakai yang menjawab pertanyaan pengujian umum, sehingga Anda tidak perlu merancang setnya sendiri. Preset pada dasarnya resep biasa, dan eject mencetak resepnya agar dapat Anda sunting dari sana. Setiap preset memiliki halamannya sendiri berisi apa yang biasanya ditemukan, isi set, dan setiap pengaturan yang diterimanya.

• Kosong dan minimal

  Apakah file valid yang sekecil yang diizinkan format dapat lolos?

  empty-and-minimal

• Penanganan nama file

  Apakah sistem saya akan menyimpan, menampilkan, dan mengembalikan nama file yang tidak diduganya?

  filename-handling

• Batas ukuran

  Apakah batas ukuran ditegakkan tepat di tempat batas itu dinyatakan?

  size-boundaries

• Impor tabel

  Apakah impor tabel saya tahan terhadap apa yang diekspor alat sungguhan?

  tabular-import

• Enkoding teks

  Apakah pembaca saya tahu enkoding suatu file, atau hanya menebak?

  text-encoding

• Validasi unggahan

  Apakah formulir unggah saya menerima yang seharusnya dan menolak sisanya?

  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 memberi tahu berapa biaya set sebelum Anda membuatnya, dan menyatakan terus terang bila sebuah angka adalah nilai sementara dari kami, bukan batas dari Anda.

Apa arti kode keluar?

Setiap akhir punya kodenya sendiri, keluaran yang terbaca mesin masuk ke keluaran standar, dan run yang gagal tidak mencetak apa pun di sana. Tabelnya adalah kontrak beku - mengubah arti sebuah kode memerlukan kenaikan versi mayor.

- 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

Run yang dihentikan dengan Ctrl+C tetap meninggalkan manifes dan tidak pernah meninggalkan file yang tertulis setengah, sehingga job yang dibatalkan masih dapat dibersihkan oleh yang berikutnya.

Workflow siap pakai untuk GitHub Actions dan GitLab CI: cara membuat file uji di pipeline CI.

Apakah ada jendela desktop?

Ada, mesin yang sama dengan jendela di atasnya, untuk pengujian yang tidak diskripkan. Ini bukan versi terpangkas: sebuah pengujian membandingkan kedua antarmuka kemampuan demi kemampuan, dan apa pun yang hanya dapat dilakukan salah satunya harus dinyatakan dan dibenarkan alih-alih diam-diam menyimpang.

Layarnya adalah satu batch, preset, beberapa batch sekaligus, dan tentang. Jendela ini menunjukkan biaya sebuah run sebelum menulis apa pun, melaporkan kemajuan selama berjalan, dan dapat dibatalkan di tengah jalan tanpa meninggalkan file yang tertulis setengah. Jendela ini belum membuka file resep - untuk saat ini resep urusan baris perintah, dan jendela membangun batch-nya di formulir.