Template:Smoke test/doc

This is a documentation subpage for Template:Smoke test.
It may contain usage information, categories and other content that is not part of the original template page.

Shortcut

{{Smoke}}

This template is rated as alpha. It is ready for third party input, and may be used on a few pages to see if problems arise, but should be watched. Suggestions for new features or changes in their input and output mechanisms are welcome.

Conditionally transcludes a template's testcases/Smoke_test page when invoked from its sandbox-transcluded /doc page. Allows immediate viewing of the effects of template sandbox changes from Preview mode without having to save the changes. This enables more efficient incremental sandbox development with immediately testable results. See § Notes for details.

Usage[edit]

{{smoke test}}
{{smoke test|heading=none|page=PageName}}

Parameters[edit]

There are two named, and three positional parameters, all optional:

|heading= – pass value none to suppress the section heading; default: emits heading ==Smoke test== on a new line.
|page= – if present, transcludes the entire contents of the given page; otherwise transcludes /testcases/Smoke test.
|1 – |3= – up to three parameters passed through to the transcluded smoke test; no meaning in this template.

Placement[edit]

Recommended placement of {{Smoke test}} is after the "Examples" section on the template documentation page.

Creating a Smoke test page[edit]

The purpose of the smoke test page is to assist a template editor in rapid and efficient testing of sandbox changes. A smoke test page is located at subpage /Smoke test of the standard template /testcases page. Any tests may be placed there, but a set of paired tests that compare live and sandbox template invocations of the same parameter set are the norm. These could be copied or styled after some of the tests on the /testcases page. In addition, some targeted test cases should be added to test the specific functionality changes being contemplated by the sandbox editor.

It is up to the sandbox editor to decide what test cases to place in the Smoke test. As with sandbox contents, the contents of a Smoke test page for a given template may change every time the sandbox is used for some new or changed feature development.

Steps[edit]

create a page named /testcases/Smoke test under the template whose sandbox you are testing
copy two or three of the more generic tests from the testcases page into Smoke test, add section header ==Regression== over it
add another section labeled after your new/changed functionality, add a few testcases that test it. Each test case should invoke the live template and the sandbox with the identical parameter set
edit the template /doc page #Examples section, tack {{smoke test}} onto the end of it and save it.

Notes[edit]

Smoke test is a convention which enables more rapid and accurate sandbox development by enabling a template editor to make incremental changes to a template sandbox and to immediately see the effects that a change will have in Preview mode, without having to go through a repeated cycle of publishing a possibly non-working version, observing results on the testcases page, reverting, and trying another change. Instead, the effects of changed sandbox code on smoke tests are updated every time the Show review button is clicked, permitting incremental progress towards a goal, which can then be published just once after a series of testable steps, knowing in advance that the saved version will work as desired, at least insofar as the Smoke test design was designed adequately to cover the sandbox changes.

The convention has three parts:

this template, i.e., {{Smoke test}}.
a page called Smoke test – this is a subpage of a testcases page, i.e., */testcases/Smoke_test. One or more tests are added to the Smoke test page to test the functional changes the template editor plans to make to the sandbox.
a /doc page transcluded from the template and template sandbox, containing an invocation of {{Smoke test}}, with or without § pass-thru parameters.

In sandbox preview mode, the {{Smoke test}} template in the /doc page invokes the /testcases/Smoke_test page (with any optional pass-thru parameters) and displays smoke test results in the transcluded /doc without having to save the sandbox changes.

If used, template {{Smoke test}} must appear within a transcluded template /doc page, typically under section Examples. When invoked from the live template, it evaluates to empty. When invoked via a sandbox-transcluded /doc page, it displays the results of transcuding the /testcases/Smoke_test. It is possible to have a Smoke test without a /testcases page above it, but the page must still be named */testcases/Smoke_test.

Positional parameters 1 – 3 are pass-through parameters. They have no use or meaning in this template, but they may have meaning in the Smoke_test page. It is up to the template editor developing upgrades in a template sandbox to also design the Smoke_test page and to determine what the meaning of the parameters are, and if they are needed.