Define LibreSign Behat taxonomy and reusable context conventions

Đang mở Phù hợp với người mới
  • Có gì không ổn?
#8,971 0 bình luận 0 reaction 0 người được giao Xem trên GitHub

Maintainer thường phản hồi trong vòng 1 ngày

Chưa có ai nhận issue này.

Đánh giá

Độ khó
2/5
Thời gian dự kiến
1-3 giờ
Mức phù hợp với người mới
78/100
Loại issue
Tài liệu
Độ rõ ràng
Đặc tả rõ ràng
Mức độ hoạt động
Sôi nổi
Công nghệ
php
Lĩnh vực
documentation, testing-qa

Hướng nghiên cứu

Tạo hoặc cập nhật tests/integration/README.md với bốn tag đã được phê duyệt, các loại trừ rõ ràng, ranh giới quyền sở hữu của Context và các quy ước thiết kế step của Behat 4. Xem xét các scenario hiện có mang tính đại diện cho hành vi của API/OCS, OCC, page/HTML và các dịch vụ phụ trợ, sau đó ghi lại các phân loại không sử dụng tag bổ sung.

Do mô hình lập chỉ mục viết ra từ nội dung của issue.

Mô tả

backend enhancement php

Part of #8969.

Context

The LibreSign Behat suite spans API/OCS calls, OCC interactions, page/HTML behavior and tests that require auxiliary services such as Mailpit, TSA or fixture servers.

Behat 4 supports Cucumber tag expressions. The suite needs a small semantic taxonomy for focused local execution and CI selection, but shard assignment must remain automatic and must not be encoded in tags.

This issue also defines where generic Nextcloud test primitives belong versus LibreSign domain steps.

Goal

Document and adopt one clear convention for Behat tags, reusable Context ownership and step design before the suite-wide application work in #8972.

Initial tag taxonomy

Use only the following execution/interface tags in the initial migration:

@api

Apply when the scenario's behavior under test is exercised primarily through HTTP API/OCS endpoints.

Do not add @api merely because setup internally uses an HTTP request.

@occ

Apply when invoking or validating an OCC command is material to the scenario behavior.

Do not add @occ merely because incidental environment setup uses OCC.

@web

Apply when the scenario validates a web/page route, HTML response or other browser-facing web behavior rather than an API/OCS contract.

This tag does not imply that Playwright/browser automation is used.

@external

Apply when the scenario requires an auxiliary service/process outside the Nextcloud application process in order to exercise the behavior, such as Mailpit, the local TSA service or a fixture HTTP service.

@external means external to the Nextcloud application process; it does not mean public Internet access.

Tags intentionally not introduced yet

Do not introduce these during this epic unless a later concrete requirement creates a separate issue:

  • manual shard/worker tags such as @shard1 or @worker2;
  • domain tags such as @signing, @certificate, @policy or @notification; the current feature-directory/name structure already carries this organization;
  • @slow; runtime classification should be introduced only after measured timings establish a concrete CI use case and an objective threshold;
  • generic @network, because most integration scenarios already involve networking and the tag would not define a useful filter.

A scenario may carry more than one of the four approved tags when the meanings independently apply.

Context/step ownership

Use this boundary:

  • libresign/nextcloud-behat: generic Nextcloud/API/OCS/OCC primitives that are reusable by another Nextcloud app;
  • LibreSign FeatureContext and LibreSign integration code: signing, certificate, participant, envelope, policy and other LibreSign-specific behavior.

Before adding a LibreSign step for generic Nextcloud behavior, check whether nextcloud-behat already provides the primitive or whether the primitive belongs there.

Do not move a step into nextcloud-behat merely to reduce code in LibreSign if its vocabulary or behavior is LibreSign-specific.

Step-design convention

New or refactored steps should:

  • describe observable behavior rather than internal implementation calls when practical;
  • keep Given/When/Then responsibility clear;
  • avoid combining unrelated actions and assertions;
  • use explicit parameter types compatible with Behat 4;
  • use DataTable or DocString when structured input is clearer than several positional parameters;
  • avoid passing hidden state between scenarios;
  • preserve useful existing step text when the contract is already clear.

Documentation location

Create or update a concise tests/integration/README.md with these code-adjacent conventions so a contributor editing a feature can find the rules without searching the epic.

Full developer execution instructions belong in the canonical LibreSign/documentation workflow handled by the final cleanup/documentation issue.

Verification

Before closing this issue, demonstrate the documented taxonomy against representative existing scenarios:

  • one API/OCS scenario;
  • one OCC scenario if present;
  • one page/HTML scenario;
  • one scenario requiring an auxiliary service.

This verification is about proving the definitions are unambiguous; the suite-wide tagging is #8972.

Done when

  • The four approved tags (@api, @occ, @web, @external) are documented with the definitions above.
  • Shard, domain, @slow and generic network tags are explicitly excluded from the initial migration.
  • Generic Nextcloud versus LibreSign domain step ownership is documented.
  • Behat 4 step-design conventions are documented.
  • tests/integration/README.md contains the code-adjacent conventions.
  • Representative existing scenarios can be classified without inventing another tag.
Ngôn ngữ chính
PHP
Star
840
Fork
173
Merge trung bình
1 ngày 9 giờ
Pull request đã merge (30 ngày)
280

Chuẩn bị môi trường

Mở trong Codespaces

Khởi chạy dev container của dự án ngay trên trình duyệt, bằng tài khoản GitHub của bạn.

Bắt đầu từ đâu

  1. Đọc hết issue, rồi đọc hướng dẫn đóng góp của dự án.
  2. Bình luận trên issue rằng bạn sẽ nhận — tránh hai người làm cùng một việc.
  3. Fork repository và làm thay đổi trên một nhánh.
  4. Mở pull request có tham chiếu số hiệu của issue.

Issue khác của LibreSign/libresign

Tất cả issue của LibreSign/libresign

Issue tương tự

Thêm issue về PHP

Nhận issue mới trong hộp thư của bạn

Bản tóm tắt ngắn những issue GitHub phù hợp với người mới.