View source for Template:Smoke test/doc

{{Documentation subpage}}
{{Tsh|Smoke}}
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 {{slink||Notes}} for details.

==Usage==
{{tlc|smoke test}}{{br}}
{{tlc|smoke test|heading{{=}}none|page{{=}}''PageName''}}

==Parameters==
There are two named, and three positional parameters, all optional:{{ublist
| {{para|heading}} – pass value {{pval|none}} to suppress the section heading; default: emits heading <code><nowiki>==Smoke test==</nowiki></code> on a new line.
| {{para|page}} – if present, transcludes the entire contents of the given page; otherwise transcludes <code>/testcases/Smoke test</code>.
| <code>{{!}}1</code> – {{para|3}} – up to three parameters passed through to the transcluded smoke test; no meaning in this template.
}}

==Placement==

Recommended placement of {{tlc|Smoke test}} is after the "Examples" section on the [[WP:template documentation|template documentation]] page.

==Creating a Smoke test page==
{{Further|Template:Smoke test/How-to}}
{{Excerpt|Template:Smoke test/How-to#Contents of a smoke test}}

=== Steps ===

{{Further|Template:Smoke test/How-to#Outline}}
{{#section:Template:Smoke test/How-to|Outline-1-4}}

==Notes==

Smoke test is a convention which enables more rapid and accurate sandbox development by enabling a template editor to make incremental changes to a [[WP:Template sandbox|template sandbox]] and to immediately see the effects that a change will have in [[WP:Preview|Preview mode]], without having to go through a repeated cycle of publishing a possibly non-working version, observing results on the [[WP:TESTCASES|testcases page]], reverting, and trying another change. Instead, the effects of changed sandbox code on smoke tests are updated every time the [[Help:Show preview|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., {{tl|Smoke test}}. 
* a page called ''Smoke test'' – this is a subpage of a [[WP:TESTCASES|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 {{tl|Smoke test}}, with or without [[#Parameters|§&nbsp;pass-thru parameters]]. 
In sandbox preview mode, the {{tl|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 {{tl|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.

== See also ==
* [[WP:Template sandbox and test cases]]
* [[Help:Template]], the main technical help page on templates, provides information on creating and using templates
* [[Help:Transclusion]]
* [[Wikipedia:Template namespace]], guidelines and tips for use of templates
* [[Wikipedia:WikiProject Templates]], the WikiProject that looks after template-related issues
* [[Special:ExpandTemplates]], expands all templates recursively
<includeonly>{{sandbox other||
<!-- Categories below this line; interwikis at Wikidata -->
[[Category:Wikipedia formatting templates]]
[[Category:Template namespace templates]]
}}</includeonly>