Trong kiến trúc của Pytest, các đối tượng nội bộ đóng vai trò then chốt để quản lý vòng đời kiểm thử, từ khâu thu thập (collection) đến thực thi và báo cáo. Dưới đây là chi tiết về các lớp đối tượng chính thường gặp khi làm việc sâu với API của Pytest.

Đối tượng CallInfo

Lớp CallInfo đóng gói thông tin về kết quả hoặc ngoại lệ phát sinh trong quá trình thực thi một lời gọi hàm. Nó lưu trữ trạng thái cuối cùng của quá trình chạy test.

Đối tượng Class

Lớp Class kế thừa từ _pytest.python.PyCollector. Đây là nút thu thập đại diện cho các lớp kiểm thử.

• collect(): Trả về danh sách các con (bao gồm các item và collector) thuộc节点 này.

Đối tượng Collector

Lớp cơ sở Collector (kế thừa _pytest.nodes.Node) chịu trách nhiệm xây dựng cây thu thập kiểm thử thông qua việc tạo các nút con.

• exception CollectError: Ngoại lệ cơ sở khi quá trình thu thập gặp lỗi, kèm theo thông báo tùy chỉnh.
• collect(): Liệt kê các phần tử con của节点 thu thập.
• repr_failure(excinfo): Tạo biểu diễn chuỗi cho lỗi thu thập.

Đối tượng Config

Lớp Config cung cấp quyền truy cập vào các mục cấu hình, trình quản lý plugin và các hook.

• option: Truy cập tùy chọn dòng lệnh dưới dạng thuộc tính (đã lỗi thời, nên dùng getoption()).
• pluginmanager: Instance quản lý các plugin.
• add_cleanup(func): Đăng ký hàm gọi khi đối tượng config không còn được sử dụng.
• classmethod fromdictargs(option_dict, args): Hàm khởi tạo hỗ trợ cho các tiến trình con.
• addinivalue_line(name, line): Thêm dòng vào tùy chọn trong file ini. Tùy chọn phải được khai báo trước.
• getini(name): Lấy giá trị cấu hình từ file ini. Sẽ ném lỗi ValueError nếu tên chưa được đăng ký qua parser.addini.
• getoption(name, default=<notset>, skip=False): Lấy giá trị tùy chọn dòng lệnh.
  • name: Tên tùy chọn hoặc chuỗi literal --OPT.
  • default: Giá trị mặc định nếu tùy chọn không tồn tại.
  • skip: Nếu True, sẽ ném pytest.skip khi tùy chọn không tồn tại hoặc bằng None.

Đối tượng ExceptionInfo

Lớp ExceptionInfo(excinfo, striptext='', traceback=None) bao bọc đối tượng sys.exc_info() và hỗ trợ điều hướng traceback.

• classmethod from_current(exprinfo=None): Trả về ExceptionInfo khớp với traceback hiện tại (API thực nghiệm).
• for_later(): Trả về một ExceptionInfo chưa được điền dữ liệu.
• type, value, tb: Truy cập lớp ngoại lệ, giá trị và traceback gốc.
• exconly(tryshort=False): Trả về chuỗi biểu diễn ngoại lệ. Nếu tryshort là True và là AssertionError, sẽ loại bỏ phần đầu dư thừa.
• errisinstance(exc): Kiểm tra xem ngoại lệ có phải là instance của exc không.
• getrepr(...): Trả về biểu diễn chuỗi của thông tin ngoại lệ với các tùy chọn hiển thị local, style traceback, v.v.
• match(regexp): So khớp biểu thức chính quy với chuỗi ngoại lệ. Trả về True nếu khớp, ngược lại ném AssertionError.

Đối tượng FixtureDef

Lớp FixtureDef là container chứa định nghĩa của một factory fixture.

Đối tượng FSCollector

Lớp FSCollector kế thừa từ _pytest.nodes.Collector, dùng để thu thập các tệp tin trong hệ thống.

Đối tượng Function

Lớp Function đại diện cho một hàm kiểm thử Python, chịu trách nhiệm thiết lập và thực thi.

• originalname: Tên hàm gốc chưa bị biến đổi bởi decorator (ví dụ không có hậu tố tham số hóa).
• function: Đối tượng hàm Python thực tế.
• runtest(): Thực thi hàm test.
• setup(): Thực hiện các bước thiết lập trước khi test chạy.

Đối tượng Item

Lớp Item là nút lá cơ bản trong cây thu thập, đại diện cho một lần gọi test. Một hàm đơn lẻ có thể sinh ra nhiều Item.

• user_properties: Danh sách các tuple (tên, giá trị) lưu trữ thuộc tính tùy chỉnh của test.
• add_report_section(when, key, content): Thêm một phần báo cáo mới.

  item.add_report_section("teardown", "custom_log", "Dữ liệu gỡ lỗi")

  • when: Giai đoạn捕获 ("setup", "call", "teardown").
  • key: Tên phần, ví dụ "stdout", "stderr" hoặc tên tùy chỉnh.
  • content: Nội dung chuỗi đầy đủ.

Đối tượng MarkDecorator

Lớp MarkDecorator dùng để trang trí cho hàm test hoặc lớp test. Khi áp dụng, nó tạo ra đối tượng MarkInfo có thể truy xuất qua hook.

speed_mark = pytest.mark.performance              # MarkDecorator đơn giản
latency_mark = pytest.mark.latency(level=1)       # MarkDecorator có tham số

Sử dụng như một decorator:

@latency_mark
def test_response_time():
    pass

Khi gọi instance MarkDecorator:

1. Nếu truyền duy nhất một lớp làm tham số vị trí: Tự động áp dụng cho mọi test trong lớp đó.
2. Nếu truyền duy nhất một hàm: Gắn đối tượng MarkInfo vào hàm với các tham số đã lưu.
3. Trường hợp khác: Trả về một MarkDecorator mới với nội dung được cập nhật bởi tham số truyền vào.

• name, args, kwargs: Các alias truy cập thông tin mark.
• with_args(*args, **kwargs): Trả về MarkDecorator với các tham số bổ sung.

Đối tượng MarkGenerator

Lớp MarkGenerator là factory tạo ra các đối tượng MarkDecorator, được phơi bày dưới dạng singleton pytest.mark.

Đối tượng Mark

Lớp Mark(name: str, args, kwargs) lưu trữ thông tin metadata.

• combined_with(other): Kết hợp với một mark khác bằng cách nối args và gộp kwargs.

Đối tượng Metafunc

Lớp Metafunc được truyền vào hook pytest_generate_tests. Nó giúp kiểm tra hàm test và sinh ra các trường hợp test dựa trên cấu hình.

• config, module, function, cls: Truy cập đối tượng cấu hình, module, hàm test và lớp chứa.
• fixturenames: Tập hợp tên các fixture cần thiết.
• parametrize(argnames, argvalues, indirect=False, ids=None, scope=None): Thêm các lời gọi mới vào hàm test cơ sở với các giá trị tham số.
  • argnames: Chuỗi tên tham số cách nhau bởi dấu phẩy hoặc list/tuple.
  • argvalues: List các giá trị. Nếu nhiều argnames, mỗi phần tử phải là tuple N giá trị.
  • indirect: Nếu True, giá trị sẽ được truyền vào fixture tương ứng thay vì trực tiếp vào hàm test.
  • ids: List chuỗi ID hoặc hàm callable để tạo ID cho từng trường hợp test.
  • scope: Phạm vi của tham số hóa, có thể ghi đè scope của fixture.

Đối tượng Module

Lớp Module kế thừa từ _pytest.nodes.File và _pytest.python.PyCollector. Đây là collector cho các lớp và hàm test trong một file.

• collect(): Trả về danh sách các con của节点 module.

Đối tượng Node

Lớp Node là cơ sở cho Collector và Item trong cây thu thập. Collector có con, Item là nút终端.

• name, parent, config, session: Thông tin định danh và ngữ cảnh.
• fspath: Đường dẫn hệ thống tệp (có thể là None).
• keywords, own_markers: Các từ khóa và marker thuộc về节点 này.
• ihook: Proxy để gọi các hook của pytest.
• warn(warning): Phát ra cảnh báo cho item này.

  current_node.warn(PytestWarning("Cảnh báo cấu hình"))

• nodeid: Chuỗi định danh địa chỉ trong cây thu thập.
• add_marker(marker, append=True): Thêm marker động vào节点.
• iter_markers(name=None): Lặp qua các marker của节点.
• get_closest_marker(name, default=None): Lấy marker gần nhất theo thứ tự từ hàm lên module.
• addfinalizer(fin): Đăng ký hàm gọi khi kết thúc节点 này.

Đối tượng Parser

Lớp Parser xử lý việc phân tích đối số dòng lệnh và giá trị file ini.

• extra_info: Dict chứa thông tin hiển thị khi lỗi phân tích dòng lệnh.
• getgroup(name, description='', after=None): Lấy hoặc tạo nhóm tùy chọn.
• addoption(*opts, **attrs): Đăng ký tùy chọn dòng lệnh mới.
• addini(name, help, type=None, default=None): Đăng ký tùy chọn trong file ini.
  • type: Có thể là pathlist, args, linelist, hoặc bool.

Đối tượng PluginManager

Lớp PluginManager quản lý việc đăng ký plugin và gọi hook 1:N.

• register(plugin, name=None): Đăng ký plugin. Trả về tên chuẩn hoặc None nếu bị chặn.
• unregister(plugin=None, name=None): Hủy đăng ký plugin.
• add_hookspecs(module_or_class): Thêm đặc tả hook mới từ module hoặc lớp.
• get_plugins(), is_registered(plugin): Kiểm tra và lấy danh sách plugin.
• load_setuptools_entrypoints(group, name=None): Load plugin từ entry points của setuptools.
• add_hookcall_monitoring(before, after): Thêm hàm theo dõi trước/sau khi gọi hook.
• enable_tracing(): Bật chế độ theo dõi gọi hook.

Đối tượng PytestPluginManager

Lớp PytestPluginManager kế thừa pluggy.manager.PluginManager, mở rộng thêm các chức năng đặc thù cho pytest như load conftest.py, biến môi trường, v.v.

• import_plugin(modname, consideration_entry_points=False): Import plugin theo tên module.
• consider_conftest, consider_env, consider_module: Các phương thức xử lý nguồn plugin khác nhau.

Đối tượng Session

Lớp Session đại diện cho một phiên chạy test hoàn chỉnh, kế thừa từ _pytest.nodes.FSCollector.

• exception Interrupted: Báo hiệu việc chạy test bị ngắt (ví dụ Ctrl+C).
• exception Failed: Báo hiệu việc chạy test dừng do lỗi nghiêm trọng.
• collect(): Thu thập các nút con trong phiên làm việc.

Đối tượng TestReport

Lớp TestReport lưu trữ kết quả của một lần chạy test (bao gồm cả setup và teardown).

• nodeid, location, keywords: Thông tin định danh và vị trí test.
• outcome: Kết quả ("passed", "failed", "skipped").
• longrepr: Biểu diễn chi tiết khi lỗi.
• when: Giai đoạn thực thi ('setup', 'call', 'teardown').
• sections: Danh sách thông tin bổ sung (stdout, stderr).
• duration: Thời gian thực thi.
• caplog, capstderr, capstdout: Nội dung捕获 được nếu bật tính năng này.
• head_line: Dòng tiêu đề hiển thị khi có lỗi (thực nghiệm).
• longreprtext: Chuỗi đầy đủ của longrepr.

Đối tượng _Result

Lớp _Result(result, excinfo) đại diện cho kết quả của một lần gọi hook.

• result: Lấy kết quả (đã lỗi thời, dùng get_result()).
• force_result(result): Ép buộc kết quả của hook. Nếu hook là firstresult, chỉ set một giá trị, ngược lại sửa danh sách kết quả. Các ngoại lệ sẽ bị xóa.
• get_result(): Lấy kết quả thực tế của lần gọi hook.