Tài liệu

Có những lệnh nào?

Mỗi lệnh làm đúng một việc:

tfg generate    tạo tệp, từ công thức hoặc từ các cờ
tfg validate    kiểm tra công thức và không ghi gì cả
tfg verify      kiểm tra một thư mục đối chiếu với manifest
tfg cleanup     xóa các tệp mà manifest liệt kê
tfg recipe fmt  in công thức ở dạng chuẩn hóa
tfg preset      dựng một bộ tệp từ một câu hỏi kiểm thử có tên
tfg formats     liệt kê các định dạng bản dựng này hỗ trợ
tfg damage      liệt kê các cách bản dựng này có thể cố ý làm hỏng một tệp
tfg tool        các tiện ích nhỏ cho tệp bạn đã có
tfg version     in phiên bản công cụ
tfg license     in giấy phép và ý nghĩa của nó với tệp được tạo

Làm sao tạo một tệp đơn có kích thước chính xác?

Nêu định dạng, kích thước và nơi đặt. Kích thước đếm theo 1024, nên 2mb là 2097152 byte. Số byte thuần cũng được, nên --size 10485761 yêu cầu đúng chừng đó.

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

Các cờ hữu ích của generate:

Làm sao tạo một tệp cố ý bị hỏng?

Mọi tệp khác mà công cụ này ghi đều đúng theo cách xây dựng, điều đó trả lời hai trong ba câu hỏi mà trình kiểm tra tải lên đặt ra. --damage trả lời câu thứ ba - tệp có mở được không. Tệp được tạo bình thường rồi bị làm hỏng, nên nó vẫn có kích thước bạn đã yêu cầu.

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

Các thiết lập đặt sau dấu hai chấm. Cờ lặp lại được, và thứ tự bạn viết là thứ tự chúng được áp dụng. tfg damage liệt kê những gì bản dựng này làm được và mỗi kiểu nhận gì.

Trong công thức, khóa là một danh sách, gồm tên hoặc thiết lập:

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

Tệp bị làm hỏng nhận expected: reject trong manifest, kèm kiểu hỏng được ghi bên cạnh. Hai thứ bị từ chối trước khi ghi bất cứ gì, vì mỗi thứ sẽ đặt lên đĩa một tệp mà manifest mô tả sai:

• tệp nhỏ hơn mức kiểu hỏng cần, vì nó sẽ ra mà không thay đổi
• expected: accept bên cạnh một kiểu hỏng, vì không gì có thể đáp ứng. Hãy viết sanitize nếu hệ thống được kiểm thử phải sửa tệp, hoặc unspecified nếu đó chính là câu hỏi bạn đang đặt

Thứ ba không thể biết trước. Nếu một kiểu hỏng chạy mà không đổi byte nào, tệp đó bị bỏ thay vì được ghi - lần chạy tiếp tục, nói đó là tệp nào và kết thúc bằng mã thoát một phần.

Từng bước, với một bài kiểm thử đọc manifest: cách tạo tệp bị hỏng để kiểm thử.

Một công thức trông thế nào?

Công thức là một tệp YAML mô tả cả một lần chạy. Hãy commit nó bên cạnh các bài kiểm thử và fixture thôi là tệp nhị phân trong kho mã - ai cũng có thể dựng lại chúng, từng byte, từ một tệp vài trăm ký tự.

# 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

Mỗi target cần đúng một trong size, size-range, boundary hoặc contains. Hai cái là lỗi và không cái nào cũng là lỗi. Công thức không hợp lệ ghi không tệp nào và báo mọi vấn đề cùng lúc thay vì chỉ cái đầu, mỗi cái nêu thiết lập mà nó nói đến.

Làm sao khai báo hệ thống của tôi cần làm gì với một tệp?

Dạng ngắn khi kết quả là đủ, dạng dài khi lý do quan trọng:

expected: accept

expected:
  outcome: reject
  reason: size_limit

Các kết quả là accept, reject, sanitize và unspecified. Các lý do là một danh sách đóng để báo cáo có thể nhóm theo chúng: 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 và size_zero.

Một lý do nêu quy tắc đang áp dụng, không phải phán quyết. Vì vậy cùng một lý do có thể nằm dưới cả hai kết quả - tệp thấp hơn giới hạn một byte là accept, và quy tắc liên quan vẫn là size_limit.

Manifest chứa gì?

Nó được ghi bên cạnh các tệp ở cuối mỗi lần chạy, kể cả lần chạy bị ngắt. Một mục cho mỗi tệp:

{
  "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 được thêm khi lần chạy đến từ một công thức, và preset cùng overrides khi nó đến từ một preset, nên manifest luôn truy ngược được về thứ đã tạo ra nó.

Mỗi mục còn mang target_id, id của target trong công thức đã tạo tệp, và summary.by_target đếm số tệp mà mỗi target tạo ra. Một công thức có nhiều target nhờ vậy kiểm tra được từng target mà không cần đọc tên tệp.

Preset là gì?

Một bộ tệp dựng sẵn trả lời một câu hỏi kiểm thử thường gặp, để bạn không phải tự thiết kế bộ. Preset thực chất là công thức bình thường, và eject in công thức ra để bạn chỉnh sửa từ đó. Mỗi preset có trang riêng nói nó thường tìm thấy gì, trong bộ có gì và mọi thiết lập nó nhận.

• Rỗng và tối thiểu

  Một tệp hợp lệ và nhỏ nhất mà định dạng cho phép có qua được không?

  empty-and-minimal

• Xử lý tên tệp

  Hệ thống của tôi có lưu, hiển thị và trả lại một tên tệp mà nó không ngờ tới không?

  filename-handling

• Ranh giới kích thước

  Giới hạn kích thước có được áp dụng đúng nơi nó được khai báo không?

  size-boundaries

• Nhập bảng

  Việc nhập bảng của tôi có chịu được những gì công cụ thật xuất ra không?

  tabular-import

• Mã hóa văn bản

  Trình đọc của tôi có biết tệp ở mã hóa nào, hay chỉ đoán?

  text-encoding

• Kiểm tra tải lên

  Biểu mẫu tải lên của tôi có nhận đúng thứ nó cần và từ chối phần còn lại không?

  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 cho bạn biết bộ sẽ tốn bao nhiêu trước khi dựng, và nói thẳng khi một con số là giá trị tạm của chúng tôi chứ không phải giới hạn của bạn.

Các mã thoát có nghĩa gì?

Mỗi kết cục có mã riêng, đầu ra máy đọc được đi ra đầu ra chuẩn, và lần chạy thất bại không in gì ở đó. Bảng này là một hợp đồng đóng băng - đổi nghĩa của một mã đòi hỏi tăng phiên bản chính.

- 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

Lần chạy bị dừng bằng Ctrl+C vẫn để lại manifest và không bao giờ để lại tệp ghi dở, nên tác vụ bị hủy vẫn có thể được dọn bởi tác vụ sau.

Workflow có sẵn cho GitHub Actions và GitLab CI: cách tạo tệp kiểm thử trong pipeline CI.

Có cửa sổ desktop không?

Có, cùng một động cơ với một cửa sổ phủ lên, cho kiểu kiểm thử không viết kịch bản. Nó không phải bản cắt giảm: một bài kiểm thử so sánh hai giao diện từng khả năng một, và bất cứ điều gì chỉ một bên làm được đều phải được khai báo và biện minh thay vì lặng lẽ lệch nhau.

Các màn hình là một lô, preset, nhiều lô cùng lúc và giới thiệu. Nó cho biết một lần chạy sẽ tốn bao nhiêu trước khi ghi gì, báo tiến độ khi đang chạy và có thể hủy giữa chừng mà không để lại tệp ghi dở. Nó chưa mở được tệp công thức - hiện công thức là việc của dòng lệnh, còn cửa sổ dựng các lô trong biểu mẫu.