1<!DOCTYPE html> 2<html lang="en-US"> 3 <head> 4 <meta charset="utf-8"> 5<!-- This site is hosted on Netlify. Anyone can build and deploy a site 6 like this one for free: https://netlify.new/?utm_campaign=loops&utm_source=ai-legible&utm_medium=owned&utm_content=comment&utm_id=ba90cc5e-81e2-40b5-b457-107522fd3634 7 Netlify hosting facts for this site: static/SSR served via Netlify Edge. --> 8 <meta name="viewport" content="width=device-width,initial-scale=1"> 9 <title>Upgrading from elm-program-test 2.x to 3.x | avh4/elm-program-test</title> 10 <meta name="generator" content="VuePress 1.9.7"> 11 12 <meta name="description" content=""> 13 14 <link rel="preload" href="/assets/css/0.styles.76626958.css" as="style"><link rel="preload" href="/assets/js/app.667806f6.js" as="script"><link rel="preload" href="/assets/js/2.1d215991.js" as="script"><link rel="preload" href="/assets/js/11.47227962.js" as="script"><link rel="prefetch" href="/assets/js/10.7e37fa33.js"><link rel="prefetch" href="/assets/js/3.3b1cbf3d.js"><link rel="prefetch" href="/assets/js/4.b2dec8d5.js"><link rel="prefetch" href="/assets/js/5.2b733c3b.js"><link rel="prefetch" href="/assets/js/6.feea877e.js"><link rel="prefetch" href="/assets/js/7.96fac09b.js"><link rel="prefetch" href="/assets/js/8.f5193335.js"><link rel="prefetch" href="/assets/js/9.277674e8.js"> 15 <link rel="stylesheet" href="/assets/css/0.styles.76626958.css"> 16 </head> 17 <body> 18 <div id="app" data-server-rendered="true"><div class="theme-container"><header class="navbar"><div class="sidebar-button"><svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" role="img" viewBox="0 0 448 512" class="icon"><path fill="currentColor" d="M436 124H12c-6.627 0-12-5.373-12-12V80c0-6.627 5.373-12 12-12h424c6.627 0 12 5.373 12 12v32c0 6.627-5.373 12-12 12zm0 160H12c-6.627 0-12-5.373-12-12v-32c0-6.627 5.373-12 12-12h424c6.627 0 12 5.373 12 12v32c0 6.627-5.373 12-12 12zm0 160H12c-6.627 0-12-5.373-12-12v-32c0-6.627 5.373-12 12-12h424c6.627 0 12 5.373 12 12v32c0 6.627-5.373 12-12 12z"></path></svg></div> <a href="/" class="home-link router-link-active"><!----> <span class="site-name">avh4/elm-program-test</span></a> <div class="links"><div class="search-box"><input aria-label="Search" autocomplete="off" spellcheck="false" value=""> <!----></div> <nav class="nav-links can-hide"><div class="nav-item"><a href="/" class="nav-link"> 19 Guidebooks 20</a></div><div class="nav-item"><a href="https://package.elm-lang.org/packages/avh4/elm-program-test/latest" target="_blank" rel="noopener noreferrer" class="nav-link external"> 21 API Documentation 22 <span><svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" focusable="false" x="0px" y="0px" viewBox="0 0 100 100" width="15" height="15" class="icon outbound"><path fill="currentColor" d="M18.8,85.1h56l0,0c2.2,0,4-1.8,4-4v-32h-8v28h-48v-48h28v-8h-32l0,0c-2.2,0-4,1.8-4,4v56C14.8,83.3,16.6,85.1,18.8,85.1z"></path> <polygon fill="currentColor" points="45.7,48.7 51.3,54.3 77.2,28.5 77.2,37.2 85.2,37.2 85.2,14.9 62.8,14.9 62.8,22.9 71.5,22.9"></polygon></svg> <span class="sr-only">(opens new window)</span></span></a></div> <a href="https://github.com/avh4/elm-program-test" target="_blank" rel="noopener noreferrer" class="repo-link"> 23 GitHub 24 <span><svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" focusable="false" x="0px" y="0px" viewBox="0 0 100 100" width="15" height="15" class="icon outbound"><path fill="currentColor" d="M18.8,85.1h56l0,0c2.2,0,4-1.8,4-4v-32h-8v28h-48v-48h28v-8h-32l0,0c-2.2,0-4,1.8-4,4v56C14.8,83.3,16.6,85.1,18.8,85.1z"></path> <polygon fill="currentColor" points="45.7,48.7 51.3,54.3 77.2,28.5 77.2,37.2 85.2,37.2 85.2,14.9 62.8,14.9 62.8,22.9 71.5,22.9"></polygon></svg> <span class="sr-only">(opens new window)</span></span></a></nav></div></header> <div class="sidebar-mask"></div> <aside class="sidebar"><nav class="nav-links"><div class="nav-item"><a href="/" class="nav-link"> 25 Guidebooks 26</a></div><div class="nav-item"><a href="https://package.elm-lang.org/packages/avh4/elm-program-test/latest" target="_blank" rel="noopener noreferrer" class="nav-link external"> 27 API Documentation 28 <span><svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" focusable="false" x="0px" y="0px" viewBox="0 0 100 100" width="15" height="15" class="icon outbound">
28<path fill="currentColor" d="M18.8,85.1h56l0,0c2.2,0,4-1.8,4-4v-32h-8v28h-48v-48h28v-8h-32l0,0c-2.2,0-4,1.8-4,4v56C14.8,83.3,16.6,85.1,18.8,85.1z"></path> <polygon fill="currentColor" points="45.7,48.7 51.3,54.3 77.2,28.5 77.2,37.2 85.2,37.2 85.2,14.9 62.8,14.9 62.8,22.9 71.5,22.9"></polygon></svg> <span class="sr-only">(opens new window)</span></span></a></div> <a href="https://github.com/avh4/elm-program-test" target="_blank" rel="noopener noreferrer" class="repo-link"> 29 GitHub 30 <span><svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" focusable="false" x="0px" y="0px" viewBox="0 0 100 100" width="15" height="15" class="icon outbound"><path fill="currentColor" d="M18.8,85.1h56l0,0c2.2,0,4-1.8,4-4v-32h-8v28h-48v-48h28v-8h-32l0,0c-2.2,0-4,1.8-4,4v56C14.8,83.3,16.6,85.1,18.8,85.1z"></path> <polygon fill="currentColor" points="45.7,48.7 51.3,54.3 77.2,28.5 77.2,37.2 85.2,37.2 85.2,14.9 62.8,14.9 62.8,22.9 71.5,22.9"></polygon></svg> <span class="sr-only">(opens new window)</span></span></a></nav> <ul class="sidebar-links"><li><section class="sidebar-group depth-0"><p class="sidebar-heading open"><span>Upgrading from elm-program-test 2.x to 3.x</span> <!----></p> <ul class="sidebar-links sidebar-group-items"><li><a class='sidebar-link' href='/upgrade-3.0.0#new-module-name-programtest'>New module name ProgramTest</a><ul class="sidebar-sub-headers"></ul></li><li><a class='sidebar-link' href='/upgrade-3.0.0#updated-api-for-starting-tests'>Updated API for starting tests</a><ul class="sidebar-sub-headers"></ul></li><li><a class='sidebar-link' href='/upgrade-3.0.0#updated-api-for-assertions'>Updated API for assertions</a><ul class="sidebar-sub-headers"></ul></li><li><a class='sidebar-link' href='/upgrade-3.0.0#other-renamed-functions'>Other renamed functions</a><ul class="sidebar-sub-headers"></ul></li><li><a class='sidebar-link' href='/upgrade-3.0.0#direct-support-for-http-ports-and-time'>Direct support for HTTP, ports, and time</a><ul class="sidebar-sub-headers"></ul></li></ul></section></li></ul> </aside> <main class="page"> <div class="theme-default-content content__default"><h1 id="upgrading-from-elm-program-test-2-x-to-3-x"><a href="#upgrading-from-elm-program-test-2-x-to-3-x" class="header-anchor">#</a> Upgrading from elm-program-test 2.x to 3.x</h1> <p>The new version of elm-program-test makes some significant changes to show tests are created, 31and makes a handful of other changes to the API. 32The list items throughout this document starting with "ð" are a checklist of steps to follow when upgrading.</p> <h2 id="new-module-name-programtest"><a href="#new-module-name-programtest" class="header-anchor">#</a> New module name <code>ProgramTest</code></h2> <p>The central module in elm-program-test has been renamed from <code>TestContext</code> to <code>ProgramTest</code>. 33The new name is meant to be a more conrete and meaningful term, 34and is meant to be easier to remember, as it now matches the package name (elm-program-test). 35The order of the type arguments has also changed to more closely match <a href="https://package.elm-lang.org/packages/elm/core/latest/Platform#Program" target="_blank" rel="noopener noreferrer">elm/core's <code>Platform.Program</code><span><svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" focusable="false" x="0px" y="0px" viewBox="0 0 100 100" width="15" height="15" class="icon outbound"><path fill="currentColor" d="M18.8,85.1h56l0,0c2.2,0,4-1.8,4-4v-32h-8v28h-48v-48h28v-8h-32l0,0c-2.2,0-4,1.8-4,4v56C14.8,83.3,16.6,85.1,18.8,85.1z"></path> <polygon fill="currentColor" points="45.7,48.7 51.3,54.3 77.2,28.5 77.2,37.2 85.2,37.2 85.2,14.9 62.8,14.9 62.8,22.9 71.5,22.9"></polygon></svg> <span class="sr-only">(opens new window)</span></span></a>.</p> <ul><li>ð Rename all references to <code>TestContext</code> -> <code>ProgramTest</code></li> <li>ð swap the order of the first two type arguments of any references to the <code>ProgramTest</code> type (<code>TestContext msg model effect</code> becomes <code>ProgramTest model msg effect</code>)</li></ul> <h2 id="updated-api-for-starting-tests"><a href="#updated-api-for-starting-tests" class="header-anchor">#</a> Updated API for starting tests</h2> <p>In elm-program-test 2.x, there was a large set of <code>create...</code> functions
36and you had to choose the one that exactly matches how you wanted to configure your test. 37In <strong>elm-program-test 3.x</strong>, there are now three groups of functions that can be combined in different ways for more flexibility, and the new API is more aligned with the design of Elm 0.19's elm/browser package. The new groups are as follows:</p> <ul><li><a href="https://package.elm-lang.org/packages/avh4/elm-program-test/latest/ProgramTest#creating-program-definitions" target="_blank" rel="noopener noreferrer"><strong><code>create...</code></strong> functions<span><svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" focusable="false" x="0px" y="0px" viewBox="0 0 100 100" width="15" height="15" class="icon outbound"><path fill="currentColor" d="M18.8,85.1h56l0,0c2.2,0,4-1.8,4-4v-32h-8v28h-48v-48h28v-8h-32l0,0c-2.2,0-4,1.8-4,4v56C14.8,83.3,16.6,85.1,18.8,85.1z"></path> <polygon fill="currentColor" points="45.7,48.7 51.3,54.3 77.2,28.5 77.2,37.2 85.2,37.2 85.2,14.9 62.8,14.9 62.8,22.9 71.5,22.9"></polygon></svg> <span class="sr-only">(opens new window)</span></span></a> that parallel the functions in elm/browser that create Programs. Use the create function that corresponds to the elm/browser function used in your Main module. (For example, if your program uses <code>Browser.document</code>, then use <code>ProgramTest.createDocument</code> in your tests.)</li> <li><a href="https://package.elm-lang.org/packages/avh4/elm-program-test/latest/ProgramTest#start" target="_blank" rel="noopener noreferrer">the <strong><code>start</code></strong> function<span><svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" focusable="false" x="0px" y="0px" viewBox="0 0 100 100" width="15" height="15" class="icon outbound"><path fill="currentColor" d="M18.8,85.1h56l0,0c2.2,0,4-1.8,4-4v-32h-8v28h-48v-48h28v-8h-32l0,0c-2.2,0-4,1.8-4,4v56C14.8,83.3,16.6,85.1,18.8,85.1z"></path> <polygon fill="currentColor" points="45.7,48.7 51.3,54.3 77.2,28.5 77.2,37.2 85.2,37.2 85.2,14.9 62.8,14.9 62.8,22.9 71.5,22.9"></polygon></svg> <span class="sr-only">(opens new window)</span></span></a> is used to initialize the <code>ProgramTest</code> state from the <code>ProgramDefinition</code> created by the <code>create...</code> functions. You'll pass the program's inital flags whan calling <code>start</code> (or pass <code>()</code> if your program doesn't use flags).</li> <li><a href="https://package.elm-lang.org/packages/avh4/elm-program-test/latest/ProgramTest#options" target="_blank" rel="noopener noreferrer">optional <strong><code>with...</code></strong> functions<span><svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" focusable="false" x="0px" y="0px" viewBox="0 0 100 100" width="15" height="15" class="icon outbound"><path fill="currentColor" d="M18.8,85.1h56l0,0c2.2,0,4-1.8,4-4v-32h-8v28h-48v-48h28v-8h-32l0,0c-2.2,0-4,1.8-4,4v56C14.8,83.3,16.6,85.1,18.8,85.1z"></path> <polygon fill="currentColor" points="45.7,48.7 51.3,54.3 77.2,28.5 77.2,37.2 85.2,37.2 85.2,14.9 62.8,14.9 62.8,22.9 71.5,22.9"></polygon></svg> <span class="sr-only">(opens new window)</span></span></a> that can be used to further configure your test before calling <code>start</code>.</li></ul> <p>You'll need to familiarize yourself with the <code>create...</code> and <code>start</code> functions 38and update to the new API in a way that's appropriate for your specific program.</p> <ul><li>ð Update creation of your tests to use the new API</li></ul> <h2 id="updated-api-for-assertions"><a href="#updated-api-for-assertions" class="header-anchor">#</a> Updated API for assertions</h2> <p>All assertion/"should"/"expect" functions have been updated to have more consistent naming. 39There are now two parallel functions for each assertion: 40one starting with <code>expect...</code> which returns an <code>Expectation</code>, meaning it should be used at the end of a test; 41and one starting with <code>ensure...</code> which returns a <code>ProgramTest</code>, meaning it can be used in the middle of a test.</p> <p>Here's a full list of changes to existing assertion functions.</p> <ul><li>ð Rename uses of the following functions: 42<ul><li><code>assertHttpRequest</code> -> <code>expectHttpRequestWasMade</code> (and it now takes the method and URL as two String parameters instead of as fields in a record parameter)</li> <li><code>
42shouldHave</code> -> <code>ensureViewHas</code></li> <li><code>shouldNotHave</code> -> <code>ensureViewHasNot</code></li> <li><code>shouldHaveView</code> -> <code>ensureView</code></li> <li><code>shouldHaveLastEffect</code> -> <code>ensureLastEffect</code></li></ul></li></ul> <h2 id="other-renamed-functions"><a href="#other-renamed-functions" class="header-anchor">#</a> Other renamed functions</h2> <ul><li>ð Rename uses of the following functions: 43<ul><li><code>simulate</code> -> <code>simulateDomEvent</code></li></ul></li></ul> <h2 id="direct-support-for-http-ports-and-time"><a href="#direct-support-for-http-ports-and-time" class="header-anchor">#</a> Direct support for HTTP, ports, and time</h2> <p>If you are currently using <code>expectLastEffect</code> or <code>simulateLastEffect</code> 44to test functionality related to HTTP requests, Elm ports, or <code>Task.sleep</code>, 45there is now a much nicer API that you can use.</p> <p>See the API documentation for 46<a href="https://package.elm-lang.org/packages/avh4/elm-program-test/latest/ProgramTest#expectHttpRequestWasMade" target="_blank" rel="noopener noreferrer"><code>expectHttpRequestWasMade</code><span><svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" focusable="false" x="0px" y="0px" viewBox="0 0 100 100" width="15" height="15" class="icon outbound"><path fill="currentColor" d="M18.8,85.1h56l0,0c2.2,0,4-1.8,4-4v-32h-8v28h-48v-48h28v-8h-32l0,0c-2.2,0-4,1.8-4,4v56C14.8,83.3,16.6,85.1,18.8,85.1z"></path> <polygon fill="currentColor" points="45.7,48.7 51.3,54.3 77.2,28.5 77.2,37.2 85.2,37.2 85.2,14.9 62.8,14.9 62.8,22.9 71.5,22.9"></polygon></svg> <span class="sr-only">(opens new window)</span></span></a>, 47<a href="https://package.elm-lang.org/packages/avh4/elm-program-test/latest/ProgramTest#simulateHttpOk" target="_blank" rel="noopener noreferrer"><code>simulateHttpOk</code><span><svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" focusable="false" x="0px" y="0px" viewBox="0 0 100 100" width="15" height="15" class="icon outbound"><path fill="currentColor" d="M18.8,85.1h56l0,0c2.2,0,4-1.8,4-4v-32h-8v28h-48v-48h28v-8h-32l0,0c-2.2,0-4,1.8-4,4v56C14.8,83.3,16.6,85.1,18.8,85.1z"></path> <polygon fill="currentColor" points="45.7,48.7 51.3,54.3 77.2,28.5 77.2,37.2 85.2,37.2 85.2,14.9 62.8,14.9 62.8,22.9 71.5,22.9"></polygon></svg> <span class="sr-only">(opens new window)</span></span></a>, 48<a href="https://package.elm-lang.org/packages/avh4/elm-program-test/latest/ProgramTest#expectOutgoingPortValues" target="_blank" rel="noopener noreferrer"><code>expectOutgoingPortValues</code><span><svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" focusable="false" x="0px" y="0px" viewBox="0 0 100 100" width="15" height="15" class="icon outbound"><path fill="currentColor" d="M18.8,85.1h56l0,0c2.2,0,4-1.8,4-4v-32h-8v28h-48v-48h28v-8h-32l0,0c-2.2,0-4,1.8-4,4v56C14.8,83.3,16.6,85.1,18.8,85.1z"></path> <polygon fill="currentColor" points="45.7,48.7 51.3,54.3 77.2,28.5 77.2,37.2 85.2,37.2 85.2,14.9 62.8,14.9 62.8,22.9 71.5,22.9"></polygon></svg> <span class="sr-only">(opens new window)</span></span></a>, 49<a href="https://package.elm-lang.org/packages/avh4/elm-program-test/latest/ProgramTest#simulateIncomingPort" target="_blank" rel="noopener noreferrer"><code>simulateIncomingPort</code><span><svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" focusable="false" x="0px" y="0px" viewBox="0 0 100 100" width="15" height="15" class="icon outbound"><path fill="currentColor" d="M18.8,85.1h56l0,0c2.2,0,4-1.8,4-4v-32h-8v28h-48v-48h28v-8h-32l0,0c-2.2,0-4,1.8-4,4v56C14.8,83.3,16.6,85.1,18.8,85.1z"></path> <polygon fill="currentColor" points="45.7,48.7 51.3,54.3 77.2,28.5 77.2,37.2 85.2,37.2 85.2,14.9 62.8,14.9 62.8,22.9 71.5,22.9"></polygon></svg> <span class="sr-only">(opens new window)</span></span></a>, 50and <a href="https://package.elm-lang.org/packages/avh4/elm-program-test/latest/ProgramTest#advanceTime" target="_blank" rel="noopener noreferrer"><code>advanceTime</code><span><svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" focusable="false" x="0px" y="0px" viewBox="0 0 100 100" width="15" height="15" class="icon outbound">
50<path fill="currentColor" d="M18.8,85.1h56l0,0c2.2,0,4-1.8,4-4v-32h-8v28h-48v-48h28v-8h-32l0,0c-2.2,0-4,1.8-4,4v56C14.8,83.3,16.6,85.1,18.8,85.1z"></path> <polygon fill="currentColor" points="45.7,48.7 51.3,54.3 77.2,28.5 77.2,37.2 85.2,37.2 85.2,14.9 62.8,14.9 62.8,22.9 71.5,22.9"></polygon></svg> <span class="sr-only">(opens new window)</span></span></a> for more information. 51There are also new guidebooks <a href='/cmds'>âTesting programs with Cmdsâ</a> 52and <a href='/ports'>âTesting programs with portsâ</a> 53offering a more detailed example of how to set up such tests.</p> <ul><li>ð Replace calls to <code>expectLastEffect</code> and <code>simulateLastEffect</code> with the nicer new API where possible</li></ul></div> <footer class="page-edit"><div class="edit-link"><a href="https://github.com/avh4/elm-program-test/edit/main/docs/upgrade-3.0.0.md" target="_blank" rel="noopener noreferrer">Suggest changes to this page</a> <span><svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" focusable="false" x="0px" y="0px" viewBox="0 0 100 100" width="15" height="15" class="icon outbound"><path fill="currentColor" d="M18.8,85.1h56l0,0c2.2,0,4-1.8,4-4v-32h-8v28h-48v-48h28v-8h-32l0,0c-2.2,0-4,1.8-4,4v56C14.8,83.3,16.6,85.1,18.8,85.1z"></path> <polygon fill="currentColor" points="45.7,48.7 51.3,54.3 77.2,28.5 77.2,37.2 85.2,37.2 85.2,14.9 62.8,14.9 62.8,22.9 71.5,22.9"></polygon></svg> <span class="sr-only">(opens new window)</span></span></div> <!----></footer> <div class="page-nav"><p class="inner"><!----> <span class="next"><a href='/html'> 54 Testing programs with interactive HTML 55 </a> 56 â 57 </span></p></div> </main></div><div class="global-ui"></div></div> 58
58<script src="/assets/js/app.667806f6.js" defer></script>
58<script src="/assets/js/2.1d215991.js" defer></script>
58<script src="/assets/js/11.47227962.js" defer></script>
58 59 </body> 60</html>
Line numbers count LF bytes from the start of the resource, as the search results do. Vendor segments are library code the classifier recognised; they are stored but not indexed. Bytes are shown as Latin1 characters, one per byte.