Some kinds of resources, like user accounts or wiki pages, will be needed by many tests. This needed is only partially served by fixtures (T221098), since fixtures must not be modified. That is, a page defined as a fixture must not be deleted, a user defined as a fixture must not be blocked, etc.
In order to give tests an easy way to create resources they can modify and destroy, a mechanism very similar to fixtures is to be introduced.
- resource files are structurally identical to fixture files, except that use the "resource" key to give their name.
- resource files can depend on fixtures and use resources
- resources export their session context with variables, just like fixtures do
- resources need to ensure that they use unique names for anything they create on the server (as opposed to fixtures, which could also use well known names).
- to gain access to a resource, a test suite would reference the resource by name, in a make-resources stanza, similar to the use-fixtures stanza.
- all resource files referenced by a test suite will be run for that test suite, and make a new session context available to the test suite, under the name assigned in the use-fixtures.
use-fixtures: - Alice - Bob make-resources: Mary: AdminUser Rob: User
This makes four contexts available to the test suite: Alice, Bob, Mary, and Rob. If we assume each of them is associated with a user account on the server, then the rule is that the accounts of Alice and Bob must not be modified, since they are also used by other tests. The accounts of Mary and Rob however are fair game for modification and deletion - the resource file for AdminUser and User will (per convention) have to make sure that the accounts use unique names (probably by using p/uniq) to avoid any conflicts with other tests.
Note that the sessions state (the cookie jar) of Mary and Rob, when accessed by multiple tests within the same suite, will be isolated on a per-test basis, just as the session state of Alice and Bob are (see T227885).
Resources and fixtures should be able to import the session context of another resource, using a import-context stanza. For instance, in the example above, the AdminUser resource would itself be creating a User resource, importing the context of that user, and using the RootUser fixture to add admin permissions to it. Since the User resource is an isolated instance, not a shared singleton as a fixture would be, this modification is unproblematic. The AdminUser resource would then export the session context it imported from User. Importing a context defined by a fixture might be possible, but is probably not a good idea, since then two fixtures would be using the same session cookies.
resource: AdminUser use-fixtures: RootUser make-resources: User: User import-context: User setup: - use-session: RootUser - request: action: add-group user: User/id token: RootUser/token