flarum / flarum/framework

[2.x] Extension-to-extension testing scaffolding limitations

Open
#4,925 0 comments 0 reactions 0 assignees View on GitHub
type/bug
Dominant language
PHP
Stars
6.7k
Forks
883
Avg merge
15h 16m
Merged PRs (30d)
73

Description

In the Flarum ecosystem, which embraces extensibility and reusability through extensions, maintaining testing scaffolding becomes hard to manage in the following scenario: Extension A implements the core logic of a new feature, provides a flexible extender interface, and ships a lot of testing scaffolding along with it. Extension B integrates with Extension A's extender interface, but has to reimplement that testing scaffolding from scratch, because Composer doesn't autoload anything from another package's `autoload-dev` section. There are some known workarounds, each with pros and cons, outlined further below.

I realize this isn't inherently a Flarum-specific issue, but rather a deliberate design choice by Composer. After discussing this with @imorland, we decided to open an issue here in the framework anyway, to think through possible solutions that could help developers across the ecosystem.

An open source example where this gap shows up is `fof/upload` and its `UploadFileTrait`. Any third-party extension that wants to test something against the `fof/upload` API has to reimplement that trait itself.

There are a few ways to work around this, but only one that doesn't break tooling or CI: extract the shared testing scaffolding into a separate Composer package and move it into the autoload section instead of autoload-dev:

```json
{
"name": "acme/foobar-testing",
"autoload-dev": {},
"autoload": {
"psr-4": {
"ACME\\FooBar\\": "src/"
}
}
}
````

It can then simply be included as a dependency or dev dependency:
```json
{
"require-dev": {
"acme/foobar-testing": "^1.0"
}
}
````

This is the cleanest solution, and it's also how `flarum/testing` solves the same problem (it provides classes like `Flarum\Testing\integration\RetrievesAuthorizedUsers`, `Flarum\Testing\integration\TestCase`, and `RefreshesFormatterCache`). However the consequence of this approach is that there are more packages to maintain and makes the developer experience of writing tests slightly worse.

What I'm primarily asking in this issue is whether Flarum can recommend an idiomatic approach for extension developers to follow here, or whether there's another solution that would help.

Contributor guide

Open the contributing guide

Research direction

Start by comparing the shared testing classes in flarum/testing with fof/upload's UploadFileTrait, then review the Composer autoload and autoload-dev behavior described in the issue. Determine whether Flarum can recommend an idiomatic extension-testing approach or needs another framework solution; done means an agreed, documented direction.

Written by the indexing model from the issue text.

Assessment

Tech stack
php
Domain
developer-experience, tooling
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Needs clarification
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.