doc/PLUGIN_FEATURE_DISABLES.md
Some Etherpad plugins exist specifically to remove a baseline feature — ep_disable_chat, ep_disable_change_author_name, ep_disable_error_messages, and so on. When the plugin is installed, the feature it disables is intentionally absent.
This is awkward for CI: the core test suite asserts the disabled feature works. Without coordination, every disable plugin's CI is permanently red, every dependency bump is permanently stuck, and the green/red signal on etherpad.org/plugins becomes meaningless.
To fix that — without giving plugins a free pass to opt out of arbitrary tests — Etherpad uses a small declared-disables contract.
Tests that exercise a single feature carry a Playwright tag like @feature:chat:
test('opens chat, sends a message, makes sure it exists on the page and hides chat', {
tag: '@feature:chat',
}, async ({page}) => { ... });
test.describe('error sanitization', { tag: '@feature:error-gritter' }, () => { ... });
Tags currently in use:
@feature:chat@feature:username@feature:clear-authorship@feature:error-gritter@feature:line-numbers@feature:rtl-toggleep.json{
"name": "ep_disable_chat",
"description": "Disable chat",
"disables": ["@feature:chat"],
"parts": [...]
}
The disables field is publicly visible in the plugin's metadata and surfaces on etherpad.org/plugins, so users see the contract before installing.
bin/run-frontend-tests-with-disables.sh enforces the contract:
# .github/workflows/frontend-tests.yml
- name: Run the frontend tests
working-directory: ./etherpad-lite/src
run: ../bin/run-frontend-tests-with-disables.sh -- --project=chromium
The script reads disables (from EP_PLUGIN_DISABLES, an explicit --plugin-ep-json PATH, or auto-detection in plugin_packages/) and runs two passes:
| Pass | What it runs | Must |
|---|---|---|
| 1. Regression | Every spec not tagged with a disabled feature | Pass — proves the plugin doesn't break anything beyond what it claims to disable. |
| 2. Honesty | Every spec that is tagged with a disabled feature | Fail — proves the plugin is genuinely disabling the feature it declares. If those tests pass, the plugin's disables claim is wrong. |
Both passes have to succeed for CI to be green.
| Failure mode | Caught by |
|---|---|
| Plugin breaks an unrelated feature | Pass 1 — its tests aren't excluded, they fail, CI red. |
| Plugin claims to disable a feature but the feature still works | Pass 2 — tagged tests pass when they should fail, script exits non-zero. |
| Plugin breaks a feature without declaring it (so etherpad.org/plugins shows it as harmless) | Pass 1 — the feature's tests aren't excluded, they fail, CI red. |
Plugin lists a feature in disables it doesn't actually disable | Pass 2. |
A plugin cannot ship green with broken functionality the user can't see ahead of time.
When a core spec needs a new feature tag (because a new disable plugin needs to opt out of it):
@feature:<area> — short, lowercase, kebab-case, plural where appropriate.test() or test.describe() blocks. Multiple tags are fine: tag: ['@feature:chat', '@feature:username'].disables and pass CI."disables": ["@feature:thing"] to your ep.json..github/workflows/frontend-tests.yml with a call to bin/run-frontend-tests-with-disables.sh (see ep_disable_chat for a worked example).--grep-invert?The earlier draft of this design just told plugin maintainers to add --grep-invert "<pattern>" in CI. That works for the regression case (pass 1 above), but it lets a careless or malicious plugin silently skip arbitrary tests and present green CI on etherpad.org/plugins despite breaking unrelated functionality. Pass 2 — and the requirement that disables be declared in ep.json rather than inferred from a CI argument — closes that gap.