दस्तावेज़ीकरण

कौन सी कमांड हैं?

हर एक सिर्फ़ एक काम करती है:

tfg generate    रेसिपी या फ़्लैग से फ़ाइलें बनाएँ
tfg validate    रेसिपी जाँचें और कुछ न लिखें
tfg verify      किसी डायरेक्टरी को मैनिफ़ेस्ट से मिलाकर जाँचें
tfg cleanup     मैनिफ़ेस्ट में सूचीबद्ध फ़ाइलें हटाएँ
tfg recipe fmt  रेसिपी को उसके स्थिर रूप में छापें
tfg preset      किसी नामित टेस्ट सवाल से फ़ाइलों का सेट बनाएँ
tfg formats     इस बिल्ड के समर्थित फ़ॉर्मैट सूचीबद्ध करें
tfg damage      इस बिल्ड द्वारा किसी फ़ाइल को जानबूझकर बिगाड़ने के तरीके सूचीबद्ध करें
tfg tool        आपके पास पहले से मौजूद फ़ाइलों के लिए छोटे टूल
tfg version     टूल का संस्करण छापें
tfg license     लाइसेंस और बनाई गई फ़ाइलों के लिए उसका अर्थ छापें

सटीक आकार की एक फ़ाइल कैसे बनाऊँ?

फ़ॉर्मैट, आकार और जगह बताएँ। आकार 1024 के गुणकों में गिने जाते हैं, इसलिए 2mb 2097152 बाइट है। सादी बाइट संख्या भी चलती है, इसलिए --size 10485761 ठीक उतने ही बाइट माँगता है।

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

generate के काम के फ़्लैग:

जानबूझकर टूटी फ़ाइल कैसे बनाऊँ?

यह टूल जो भी दूसरी फ़ाइल लिखता है वह बनावट से सही होती है, और इससे अपलोड वैलिडेटर के तीन सवालों में से दो का जवाब मिल जाता है। --damage तीसरे का जवाब देता है - क्या फ़ाइल खुलती भी है। फ़ाइल सामान्य रूप से बनती है और फिर बिगाड़ी जाती है, इसलिए उसका आकार वही रहता है जो आपने माँगा।

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

सेटिंग कोलन के बाद आती हैं। फ़्लैग दोहराया जा सकता है, और आप जिस क्रम में लिखते हैं वही उनके लागू होने का क्रम है। tfg damage बताता है कि यह बिल्ड क्या कर सकता है और हर एक क्या लेता है।

रेसिपी में कुंजी एक सूची है, नामों की या सेटिंग की:

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

बिगाड़ी गई फ़ाइल को मैनिफ़ेस्ट में expected: reject मिलता है, और बिगाड़ने का ब्योरा उसके बगल में दर्ज होता है। दो चीज़ें कुछ भी लिखे जाने से पहले ठुकरा दी जाती हैं, क्योंकि हर एक डिस्क पर ऐसी फ़ाइल छोड़ देती जिसे मैनिफ़ेस्ट गलत बताता:

• बिगाड़ने के लिए ज़रूरी से छोटी फ़ाइल, क्योंकि वह बिना बदले निकल आती
• बिगाड़ के बगल में expected: accept, क्योंकि कुछ भी उसे पूरा नहीं कर सकता। अगर जाँचे जा रहे सिस्टम को फ़ाइल सुधारनी है तो sanitize लिखें, या अगर आप यही सवाल पूछ रहे हैं तो unspecified

तीसरी बात पहले से नहीं जानी जा सकती। अगर कोई बिगाड़ चलता है और एक भी बाइट नहीं हिलाता, तो वह फ़ाइल लिखे जाने के बजाय छोड़ दी जाती है - रन चलता रहता है, बताता है कि वह कौन सी फ़ाइल थी, और आंशिक एग्ज़िट कोड के साथ ख़त्म होता है।

कदम दर कदम, मैनिफ़ेस्ट पढ़ने वाले एक टेस्ट के साथ: परीक्षण के लिए खराब फ़ाइल कैसे बनाएँ।

रेसिपी कैसी दिखती है?

रेसिपी एक YAML फ़ाइल है जो पूरे रन का वर्णन करती है। इसे अपने टेस्ट के बगल में कमिट करें और फ़िक्स्चर आपकी रिपॉज़िटरी में बाइनरी नहीं रह जाते - कोई भी उन्हें कुछ सौ अक्षरों की फ़ाइल से बाइट-दर-बाइट दोबारा बना सकता है।

# 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

हर टार्गेट को size, size-range, boundary या contains में से ठीक एक चाहिए। दो होना त्रुटि है और एक भी न होना भी। अमान्य रेसिपी कोई फ़ाइल नहीं लिखती और सिर्फ़ पहली नहीं, सारी समस्याएँ एक साथ बताती है, हर एक उस सेटिंग का नाम लेकर जिससे वह जुड़ी है।

मैं कैसे बताऊँ कि मेरे सिस्टम को किसी फ़ाइल के साथ क्या करना चाहिए?

जब नतीजा काफ़ी हो तो छोटा रूप, जब कारण मायने रखे तो लंबा रूप:

expected: accept

expected:
  outcome: reject
  reason: size_limit

नतीजे हैं accept, reject, sanitize और unspecified। कारण एक बंद सूची हैं ताकि रिपोर्ट उनके आधार पर समूह बना सके: 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 और size_zero।

कारण काम कर रहे नियम का नाम लेता है, फ़ैसले का नहीं। इसीलिए एक ही कारण किसी भी नतीजे के नीचे आ सकता है - सीमा से एक बाइट नीचे की फ़ाइल accept है, और जिस नियम की बात है वह फिर भी size_limit है।

मैनिफ़ेस्ट में क्या है?

यह हर रन के अंत में फ़ाइलों के बगल में लिखा जाता है, बीच में रोके गए रन में भी। हर फ़ाइल के लिए एक प्रविष्टि:

{
  "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 जुड़ता है, और प्रीसेट से आया हो तो overrides के साथ preset, इसलिए मैनिफ़ेस्ट को हमेशा उसके स्रोत तक खोजा जा सकता है।

हर प्रविष्टि में target_id भी होता है, यानी रेसिपी के उस टार्गेट का id जिसने फ़ाइल बनाई, और summary.by_target गिनता है कि हर टार्गेट के हिस्से कितनी फ़ाइलें आईं। इसलिए कई टार्गेट वाली रेसिपी को फ़ाइल नाम पढ़े बिना टार्गेट-दर-टार्गेट जाँचा जा सकता है।

प्रीसेट क्या है?

किसी आम टेस्ट सवाल का जवाब देने वाला फ़ाइलों का तैयार सेट, ताकि आपको सेट खुद डिज़ाइन न करना पड़े। प्रीसेट अंदर से सामान्य रेसिपी हैं, और eject रेसिपी छापता है ताकि आप वहीं से उसे संपादित कर सकें। हर प्रीसेट का अपना पेज है जो बताता है कि वह आम तौर पर क्या पकड़ता है, सेट में क्या है और वह कौन सी सेटिंग लेता है।

• खाली और न्यूनतम

  क्या फ़ॉर्मैट की अनुमति जितनी छोटी वैध फ़ाइल पास हो जाती है?

  empty-and-minimal

• फ़ाइल नाम का प्रबंधन

  क्या मेरा सिस्टम ऐसा फ़ाइल नाम सहेजेगा, दिखाएगा और लौटाएगा जिसकी उसे उम्मीद नहीं थी?

  filename-handling

• आकार की सीमाएँ

  क्या आकार की सीमा ठीक वहीं लागू होती है जहाँ उसकी घोषणा की गई है?

  size-boundaries

• टेबल इंपोर्ट

  क्या मेरा टेबल इंपोर्ट वह झेल पाता है जो असली टूल एक्सपोर्ट करते हैं?

  tabular-import

• टेक्स्ट एन्कोडिंग

  क्या मेरा रीडर जानता है कि फ़ाइल किस एन्कोडिंग में है, या अंदाज़ा लगा रहा है?

  text-encoding

• अपलोड सत्यापन

  क्या मेरा अपलोड फ़ॉर्म वह लेता है जो उसे लेना चाहिए और बाकी को लौटा देता है?

  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 सेट बनाने से पहले बताता है कि उसकी क़ीमत क्या होगी, और साफ़ कहता है जब कोई संख्या आपकी सीमा नहीं बल्कि हमारी अस्थायी जगह-धारक संख्या हो।

एग्ज़िट कोड का क्या अर्थ है?

हर अंत का अपना कोड है, मशीन के पढ़ने लायक आउटपुट स्टैंडर्ड आउटपुट पर जाता है, और विफल रन वहाँ कुछ नहीं छापता। तालिका एक जमाया हुआ अनुबंध है - किसी कोड का अर्थ बदलने के लिए मुख्य संस्करण बढ़ाना पड़ता है।

- 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

Ctrl+C से रोका गया रन फिर भी मैनिफ़ेस्ट छोड़ता है और कभी आधी लिखी फ़ाइल नहीं छोड़ता, इसलिए रद्द किए गए जॉब को अगला जॉब साफ़ कर सकता है।

GitHub Actions और GitLab CI के लिए तैयार वर्कफ़्लो: CI पाइपलाइन में टेस्ट फ़ाइलें कैसे बनाएँ।

क्या डेस्कटॉप विंडो है?

हाँ, वही इंजन जिस पर एक विंडो लगी है, उस टेस्टिंग के लिए जो स्क्रिप्ट से नहीं होती। यह घटाया हुआ रूप नहीं है: एक टेस्ट दोनों इंटरफ़ेस की क्षमता-दर-क्षमता तुलना करता है, और जो सिर्फ़ एक ही कर सकता है उसे चुपचाप अलग होने देने के बजाय घोषित और उचित ठहराना पड़ता है।

स्क्रीन हैं एक बैच, प्रीसेट, एक साथ कई बैच, और परिचय। यह कुछ भी लिखने से पहले रन की क़ीमत दिखाती है, चलते समय प्रगति बताती है, और बीच में रद्द की जा सकती है बिना आधी लिखी फ़ाइल छोड़े। यह अभी रेसिपी फ़ाइल नहीं खोलती - फ़िलहाल रेसिपी कमांड लाइन की चीज़ हैं, और विंडो अपने बैच फ़ॉर्म में बनाती है।