Define LibreSign Behat taxonomy and reusable context conventions
Maintainers usually reply within 1 day
Nobody has claimed this yet.
Assessment
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Newbie friendliness
- 78/100
- Issue type
- Documentation
- Clarity
- Clearly specified
- Activity status
- Active
- Tech stack
- php
- Domain
- documentation, testing-qa
Research direction
Create or update tests/integration/README.md with the four approved tags, explicit exclusions, Context ownership boundaries, and Behat 4 step-design conventions. Review representative existing scenarios for API/OCS, OCC, page/HTML, and auxiliary-service behavior, then document classifications that use no additional tags.
Written by the indexing model from the issue text.
Description
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
@shard1or@worker2; - domain tags such as
@signing,@certificate,@policyor@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
FeatureContextand 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
DataTableorDocStringwhen 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,
@slowand 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.mdcontains the code-adjacent conventions. - Representative existing scenarios can be classified without inventing another tag.
- Dominant language
- PHP
- Stars
- 828
- Forks
- 159
- Avg merge
- 7h 43m
- Merged PRs (30d)
- 537
Getting set up
Starts the project's dev container in your browser, under your own GitHub account.
- No Dockerfile or Docker Compose file
- Has a pull request template
- Read the contributing guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
More from LibreSign/libresign
-
Difficulty 1/5 Under an hour Newbie friendliness 83/100
LibreSign/libresign#9007 · 1 reaction ·
Maintainers usually reply within 1 day
-
Validation page says "This document is valid" for a document with no signaturePossibly taken @maia-andre claimed this 7 days ago. Open
Difficulty 2/5 1-3 hours Newbie friendliness 82/100
Maintainers usually reply within 1 day
-
good first issue
Difficulty 2/5 1-3 hours Newbie friendliness 78/100
LibreSign/libresign#8284 · 5 comments ·
Maintainers usually reply within 1 day
-
backend php
Difficulty 5/5 Over a week Newbie friendliness 25/100
Maintainers usually reply within 1 day
-
backend enhancement frontend javascript php
Difficulty 4/5 3-5 days Newbie friendliness 22/100
Maintainers usually reply within 1 day
All issues in LibreSign/libresign
Similar issues
-
Difficulty 2/5 1-3 hours Newbie friendliness 65/100
Maintainers usually reply within 1 day
-
Difficulty 2/5 1-3 hours Newbie friendliness 76/100
Maintainers usually reply within 2 days
-
b:1.9 t:enhancement
Difficulty 2/5 1-3 hours Newbie friendliness 65/100
Maintainers usually reply within 3 days
-
backend bug
Difficulty 2/5 1-3 hours Newbie friendliness 76/100
-
bug
Difficulty 1/5 Under an hour Newbie friendliness 85/100