Overview

We currently develop and test Codex components in a standalone environment (basically, a single-page application / static website built using the Vite build tool). A lot of QA testing can be handled in this environment just fine. However, production use of these components will primarily take place within MediaWiki, where many things work differently.

Some limitations of our current workflow:

• Our current Codex demo tools currently have very little support for internationalization – no i18n messages defined, no ability to preview components in non-Latin scripts, etc
• Components that are embedded within a MW skin or extension will need to properly integrate with existing CSS styles, responsive behavior, and non-Vue parts of the page
• In the future MediaWiki may introduce experimental support for server-side-rendering of Vue.js features; we will need a way to ensure that Codex components work properly in this environment once this happens

Proposal

DST has already developed (and continues to maintain) a simple MediaWiki extension called VueTest: https://gerrit.wikimedia.org/r/admin/repos/mediawiki/extensions/VueTest

This extension was originally created to serve as an example to developers of how to use Vue inside a MediaWiki environment; it has never been deployed anywhere, but developers can set it up within a local MW development environment – or they can just consult the source code as a reference.

With some additional work, we can utilize the VueTest extension as a QA tool for testing out Codex components inside of MediaWiki.

1. Update the VueTest extension to display a series of sub-pages - one per component. The configurable component demos (from the Codex docs) could be embedded in these sub-pages for testing. There would be no need to include the surrounding Markdown text. However, some work will need to be done to adapt the Wrapper and Controls components for use in MW, and the Codex Demo components will need to be packaged in a way that they can be used inside MW.
2. Testers can then use https://patchdemo.wmflabs.org/ to stage a test wiki that contains the VueTest extension as wellas the latest version of Codex. Patches can be applied in order to demo unmerged components. This will let QTE folks test components in a production-like environment.
3. Demos from Codex won't fully support internationalization without being re-written. We should come back to this problem after we get everything else working.

Priority of this work

The current Codex demo pages (standalone) are suitable for about 90% of current manual testing needs, according to @EUdoh-WMF. This work would be an improvement in our testing process (it would allow us to test in a much more production-like environment) but it's not urgently needed right now.

I think that we could identify some follow up tasks here and focus on them as time allows over the next few sprints, at a secondary level of priority.

Questions

There are still some questions that must be resolved before we can settle on this approach. This spike task can be closed when all of these questions have been resolved. Some of these may necessitate the creation of new follow-up tickets.

• Codex already contains some demo code that is useful for testing each component – both in the documentation as well as in the developer sandbox page. How can we pull in this demo code (which is currently not packaged for distribution in any way) into the VueTest extension? Will we need to manually copy things over each time a new component is added?
  • Solution: Define a new sub-package for QA demos inside of Codex, see T318842: Enable embedding of Codex component demos inside of VueTest MediaWiki extension.
• How should we handle internationalization testing? Codex currently has no concept of internationalization – all content (labels, messages, slot content, etc) is seen as the responsibility of the consumer for now. VueTest can rely on MW's existing internationalization tools – including the Vue i18n plugin which exists in MW core. But to do this we will need to define i18n messages for VueTest, submit them to TranslateWiki, and then write demo code in such a way that it can use these internationalized messages instead of hard-coded strings. Doing this may make it more difficult to just import and re-use existing Codex demo code, since it is not written with any i18n system in mind.
  • Solution: Demos used inside of VueTest should be written to utilize Vue's <slot> feature, so that existing template code can be overridden when they are imported into MW; this will allow for use of MediaWiki's i18n system without having to rewrite Codex to be aware of it.
• How will QTE testers have access to VueTest? This extension is not deployed anywhere currently. We have a couple of options:
  • Solution: Use Patchdemo (see point 2 above); eventually we also hope to get this up on Beta Labs
• Can we ensure that VueTest continues to serve as good reference code for developers while making these other changes to benefit testers? Is one or the other use-case more important going forward?
  • Solution: A top level page (Special:VueTest) can remain as an example for developers to reference, while testers can use the subpages for manual testing of individual components.

Follow-up/refinements (9/28/22)

After some discussion we have decided that the best way to proceed here is to create a new sub-package of Codex that packages up component demos for use inside of the VueTest extension. Importantly, this approach will allow us to test WIP or experimental components that are not yet included in Codex public releases (similar to how the Docs site is able to access these components).

This task is tracked here: T318842: Enable embedding of Codex component demos inside of VueTest MediaWiki extension

Acceptance Criteria

• All "open questions" are answered in this ticket, and any necessary follow-up tasks have been created