nautobot 2.3.3__py3-none-any.whl → 2.3.5__py3-none-any.whl

nautobot/project-static/docs/development/core/testing.html

@@ -18,7 +18,7 @@
       
       
       <link rel="icon" href="../../assets/favicon.ico">
-      <meta name="generator" content="mkdocs-1.6.1, mkdocs-material-9.5.34">
+      <meta name="generator" content="mkdocs-1.6.1, mkdocs-material-9.5.35">
     
     
       
@@ -783,7 +783,7 @@
             
   
   <span class="md-ellipsis">
-    Installation Extras
+    Upgrading
   </span>
   
 
@@ -792,115 +792,6 @@
         
         <nav class="md-nav" data-md-level="3" aria-labelledby="__nav_2_1_2_label" aria-expanded="false">
           <label class="md-nav__title" for="__nav_2_1_2">
-            <span class="md-nav__icon md-icon"></span>
-            Installation Extras
-          </label>
-          <ul class="md-nav__list" data-md-scrollfix>
-            
-              
-                
-  
-  
-  
-  
-    <li class="md-nav__item">
-      <a href="../../user-guide/administration/installation-extras/docker.html" class="md-nav__link">
-        
-  
-  <span class="md-ellipsis">
-    Nautobot Docker Images
-  </span>
-  
-
-      </a>
-    </li>
-  
-
-              
-            
-              
-                
-  
-  
-  
-  
-    <li class="md-nav__item">
-      <a href="../../user-guide/administration/installation-extras/health-checks.html" class="md-nav__link">
-        
-  
-  <span class="md-ellipsis">
-    Health Checks
-  </span>
-  
-
-      </a>
-    </li>
-  
-
-              
-            
-              
-                
-  
-  
-  
-  
-    <li class="md-nav__item">
-      <a href="../../user-guide/administration/installation-extras/selinux-troubleshooting.html" class="md-nav__link">
-        
-  
-  <span class="md-ellipsis">
-    SELinux Troubleshooting
-  </span>
-  
-
-      </a>
-    </li>
-  
-
-              
-            
-          </ul>
-        </nav>
-      
-    </li>
-  
-
-              
-            
-              
-                
-  
-  
-  
-  
-    
-    
-    
-      
-      
-    
-    
-    <li class="md-nav__item md-nav__item--nested">
-      
-        
-        
-        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_2_1_3" >
-        
-          
-          <label class="md-nav__link" for="__nav_2_1_3" id="__nav_2_1_3_label" tabindex="0">
-            
-  
-  <span class="md-ellipsis">
-    Upgrading
-  </span>
-  
-
-            <span class="md-nav__icon md-icon"></span>
-          </label>
-        
-        <nav class="md-nav" data-md-level="3" aria-labelledby="__nav_2_1_3_label" aria-expanded="false">
-          <label class="md-nav__title" for="__nav_2_1_3">
             <span class="md-nav__icon md-icon"></span>
             Upgrading
           </label>
@@ -965,7 +856,7 @@
       
         
         
-        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_2_1_3_3" >
+        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_2_1_2_3" >
         
           
           
@@ -981,14 +872,14 @@
             </a>
             
               
-              <label class="md-nav__link " for="__nav_2_1_3_3" id="__nav_2_1_3_3_label" tabindex="0">
+              <label class="md-nav__link " for="__nav_2_1_2_3" id="__nav_2_1_2_3_label" tabindex="0">
                 <span class="md-nav__icon md-icon"></span>
               </label>
             
           </div>
         
-        <nav class="md-nav" data-md-level="4" aria-labelledby="__nav_2_1_3_3_label" aria-expanded="false">
-          <label class="md-nav__title" for="__nav_2_1_3_3">
+        <nav class="md-nav" data-md-level="4" aria-labelledby="__nav_2_1_2_3_label" aria-expanded="false">
+          <label class="md-nav__title" for="__nav_2_1_2_3">
             <span class="md-nav__icon md-icon"></span>
             Upgrading Nautobot from v1.X to v2.0
           </label>
@@ -1032,7 +923,7 @@
       
         
         
-        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_2_1_3_3_2" >
+        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_2_1_2_3_2" >
         
           
           
@@ -1048,14 +939,14 @@
             </a>
             
               
-              <label class="md-nav__link " for="__nav_2_1_3_3_2" id="__nav_2_1_3_3_2_label" tabindex="0">
+              <label class="md-nav__link " for="__nav_2_1_2_3_2" id="__nav_2_1_2_3_2_label" tabindex="0">
                 <span class="md-nav__icon md-icon"></span>
               </label>
             
           </div>
         
-        <nav class="md-nav" data-md-level="5" aria-labelledby="__nav_2_1_3_3_2_label" aria-expanded="false">
-          <label class="md-nav__title" for="__nav_2_1_3_3_2">
+        <nav class="md-nav" data-md-level="5" aria-labelledby="__nav_2_1_2_3_2_label" aria-expanded="false">
+          <label class="md-nav__title" for="__nav_2_1_2_3_2">
             <span class="md-nav__icon md-icon"></span>
             IPAM Migration Guide
           </label>
@@ -1186,10 +1077,10 @@
       
         
         
-        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_2_1_4" >
+        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_2_1_3" >
         
           
-          <label class="md-nav__link" for="__nav_2_1_4" id="__nav_2_1_4_label" tabindex="0">
+          <label class="md-nav__link" for="__nav_2_1_3" id="__nav_2_1_3_label" tabindex="0">
             
   
   <span class="md-ellipsis">
@@ -1200,8 +1091,8 @@
             <span class="md-nav__icon md-icon"></span>
           </label>
         
-        <nav class="md-nav" data-md-level="3" aria-labelledby="__nav_2_1_4_label" aria-expanded="false">
-          <label class="md-nav__title" for="__nav_2_1_4">
+        <nav class="md-nav" data-md-level="3" aria-labelledby="__nav_2_1_3_label" aria-expanded="false">
+          <label class="md-nav__title" for="__nav_2_1_3">
             <span class="md-nav__icon md-icon"></span>
             Migration
           </label>
@@ -1274,7 +1165,7 @@
       
         
         
-        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_2_1_5" >
+        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_2_1_4" >
         
           
           
@@ -1290,14 +1181,14 @@
             </a>
             
               
-              <label class="md-nav__link " for="__nav_2_1_5" id="__nav_2_1_5_label" tabindex="0">
+              <label class="md-nav__link " for="__nav_2_1_4" id="__nav_2_1_4_label" tabindex="0">
                 <span class="md-nav__icon md-icon"></span>
               </label>
             
           </div>
         
-        <nav class="md-nav" data-md-level="3" aria-labelledby="__nav_2_1_5_label" aria-expanded="false">
-          <label class="md-nav__title" for="__nav_2_1_5">
+        <nav class="md-nav" data-md-level="3" aria-labelledby="__nav_2_1_4_label" aria-expanded="false">
+          <label class="md-nav__title" for="__nav_2_1_4">
             <span class="md-nav__icon md-icon"></span>
             Configuration
           </label>
@@ -1310,11 +1201,11 @@
   
   
     <li class="md-nav__item">
-      <a href="../../user-guide/administration/configuration/required-settings.html" class="md-nav__link">
+      <a href="../../user-guide/administration/configuration/settings.html" class="md-nav__link">
         
   
   <span class="md-ellipsis">
-    Required Settings
+    Settings
   </span>
   
 
@@ -1331,11 +1222,11 @@
   
   
     <li class="md-nav__item">
-      <a href="../../user-guide/administration/configuration/optional-settings.html" class="md-nav__link">
+      <a href="../../user-guide/administration/configuration/redis.html" class="md-nav__link">
         
   
   <span class="md-ellipsis">
-    Optional Settings
+    Redis
   </span>
   
 
@@ -1383,10 +1274,10 @@
       
         
         
-        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_2_1_5_4" >
+        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_2_1_4_4" >
         
           
-          <label class="md-nav__link" for="__nav_2_1_5_4" id="__nav_2_1_5_4_label" tabindex="0">
+          <label class="md-nav__link" for="__nav_2_1_4_4" id="__nav_2_1_4_4_label" tabindex="0">
             
   
   <span class="md-ellipsis">
@@ -1397,8 +1288,8 @@
             <span class="md-nav__icon md-icon"></span>
           </label>
         
-        <nav class="md-nav" data-md-level="4" aria-labelledby="__nav_2_1_5_4_label" aria-expanded="false">
-          <label class="md-nav__title" for="__nav_2_1_5_4">
+        <nav class="md-nav" data-md-level="4" aria-labelledby="__nav_2_1_4_4_label" aria-expanded="false">
+          <label class="md-nav__title" for="__nav_2_1_4_4">
             <span class="md-nav__icon md-icon"></span>
             External Authentication
           </label>
@@ -1500,10 +1391,10 @@
       
         
         
-        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_2_1_6" >
+        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_2_1_5" >
         
           
-          <label class="md-nav__link" for="__nav_2_1_6" id="__nav_2_1_6_label" tabindex="0">
+          <label class="md-nav__link" for="__nav_2_1_5" id="__nav_2_1_5_label" tabindex="0">
             
   
   <span class="md-ellipsis">
@@ -1514,8 +1405,8 @@
             <span class="md-nav__icon md-icon"></span>
           </label>
         
-        <nav class="md-nav" data-md-level="3" aria-labelledby="__nav_2_1_6_label" aria-expanded="false">
-          <label class="md-nav__title" for="__nav_2_1_6">
+        <nav class="md-nav" data-md-level="3" aria-labelledby="__nav_2_1_5_label" aria-expanded="false">
+          <label class="md-nav__title" for="__nav_2_1_5">
             <span class="md-nav__icon md-icon"></span>
             Tools
           </label>
@@ -1588,10 +1479,10 @@
       
         
         
-        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_2_1_7" >
+        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_2_1_6" >
         
           
-          <label class="md-nav__link" for="__nav_2_1_7" id="__nav_2_1_7_label" tabindex="0">
+          <label class="md-nav__link" for="__nav_2_1_6" id="__nav_2_1_6_label" tabindex="0">
             
   
   <span class="md-ellipsis">
@@ -1602,8 +1493,8 @@
             <span class="md-nav__icon md-icon"></span>
           </label>
         
-        <nav class="md-nav" data-md-level="3" aria-labelledby="__nav_2_1_7_label" aria-expanded="false">
-          <label class="md-nav__title" for="__nav_2_1_7">
+        <nav class="md-nav" data-md-level="3" aria-labelledby="__nav_2_1_6_label" aria-expanded="false">
+          <label class="md-nav__title" for="__nav_2_1_6">
             <span class="md-nav__icon md-icon"></span>
             Guides
           </label>
@@ -1616,11 +1507,11 @@
   
   
     <li class="md-nav__item">
-      <a href="../../user-guide/administration/guides/caching.html" class="md-nav__link">
+      <a href="../../user-guide/administration/guides/docker.html" class="md-nav__link">
         
   
   <span class="md-ellipsis">
-    Caching
+    Nautobot Docker Images
   </span>
   
 
@@ -1637,11 +1528,32 @@
   
   
     <li class="md-nav__item">
-      <a href="../../user-guide/administration/guides/healthcheck.html" class="md-nav__link">
+      <a href="../../user-guide/administration/guides/selinux-troubleshooting.html" class="md-nav__link">
         
   
   <span class="md-ellipsis">
-    Health Check
+    SELinux Troubleshooting
+  </span>
+  
+
+      </a>
+    </li>
+  
+
+              
+            
+              
+                
+  
+  
+  
+  
+    <li class="md-nav__item">
+      <a href="../../user-guide/administration/guides/health-checks.html" class="md-nav__link">
+        
+  
+  <span class="md-ellipsis">
+    Health Checks
   </span>
   
 
@@ -9120,18 +9032,26 @@
 <p>Nautobot's custom <a href="https://docs.djangoproject.com/en/3.2/topics/testing/advanced/#defining-a-test-runner">test runner</a> class (<code>nautobot.core.tests.runner.NautobotTestRunner</code>) makes use of the various factories to pre-populate the test database with data before running any tests. This reduces the need for individual tests to define their own baseline data sets.</p>
 <div class="admonition info">
 <p class="admonition-title">Info</p>
-<p>Because Apps also commonly use Nautobot's test runner, the base Nautobot <code>settings.py</code> currently defaults <a href="../../user-guide/administration/configuration/optional-settings.html#test_use_factories"><code>TEST_USE_FACTORIES</code></a> to <code>False</code> so as to not negatively impact App tests that may not be designed to account for the presence of pre-populated test data in the database. This configuration is overridden to <code>True</code> in <code>nautobot/core/tests/nautobot_config.py</code> for Nautobot's own tests.</p>
+<p>Because Apps also commonly use Nautobot's test runner, the base Nautobot <code>settings.py</code> currently defaults <a href="../../user-guide/administration/configuration/settings.html#test_use_factories"><code>TEST_USE_FACTORIES</code></a> to <code>False</code> so as to not negatively impact App tests that may not be designed to account for the presence of pre-populated test data in the database. This configuration is overridden to <code>True</code> in <code>nautobot/core/tests/nautobot_config.py</code> for Nautobot's own tests.</p>
+</div>
+<div class="admonition warning">
+<p class="admonition-title">Warning</p>
+<p>Factories should generally <strong>not</strong> be called within test code, i.e. in a <code>setUp()</code> or <code>setUpTestData()</code> method. This is because factory output is <em>stateful</em>, that is to say the output of any given factory call will depend on the history of <em>all previous factory calls</em> since the process was started. This means that a call to a factory within a test case will depend on which other test cases have also called factories, and what order they were called in, as well as whether the initial test database population was done via factories or whether they were bypassed by reuse of cached test data (see below).</p>
+<p>In short, we should only have one place in our tests where factories are called, and that's the <code>generate_test_data</code> management command. Individual tests should use standard <code>create()</code> or <code>save()</code> model methods, never factories.</p>
 </div>
 <h3 id="factory-caching">Factory Caching<a class="headerlink" href="#factory-caching" title="Permanent link">&para;</a></h3>
 <details class="version-added">
 <summary>Added in version 1.5.11</summary>
 </details>
-<p>To reduce the time taken between multiple test runs, a new argument has been added to the <code>nautobot-server test</code>, <code>invoke unittest</code> and <code>invoke integration-test</code> commands: <code>--cache-test-fixtures</code>. When running one of these commands with <code>--cache-test-fixtures</code> for the first time, after the factory data has been generated it will be saved to a <code>factory_dump.json</code> file in the <code>development</code> directory. On subsequent runs of unit or integration tests, the factory data will be loaded from the file instead of being generated again. This can significantly reduce the time taken to run tests.</p>
-<p>Factory caching is disabled by default. When using the <code>invoke</code> commands to run tests, caching can be enabled by default for your development environment by setting the <code>cache_test_fixtures</code> key to <code>True</code> in the <code>invoke.yml</code> file.</p>
+<p>To reduce the time taken between multiple test runs, a new argument has been added to the <code>nautobot-server test</code> command: <code>--cache-test-fixtures</code>. When running tests with <code>--cache-test-fixtures</code> for the first time, after the factory data has been generated it will be saved to a <code>factory_dump.json</code> file in the <code>development</code> directory. On subsequent runs of unit or integration tests, if <code>--cache-test-fixtures</code> is again specified (hint: it is included by default when running <code>invoke unittest</code> or <code>invoke integration-test</code>), the factory data will be loaded from the file instead of being generated again. This can significantly reduce the time taken to run tests.</p>
 <details class="version-changed">
 <summary>Changed in version 2.2.7 — Hashing of migrations in the factory dump</summary>
 <p>The test runner now calculates a hash of applied database migrations and uses that as a key when creating/locating the factory data file. This serves as a way to avoid inadvertently using cached test data from the wrong branch or wrong set of migrations, and reduces the frequency with which you might need to manually delete the fixture file. For example, the set of migrations present in <code>develop</code> might result in a <code>factory_dump.966e2e1ed4ae5f924d54.json</code>, while those in <code>next</code> might result in <code>factory_dump.72b71317c5f5c047493e.json</code> - both files can coexist, and when you switch between branches during development, the correct one will automatically be selected.</p>
 </details>
+<details class="version-changed">
+<summary>Changed in version 2.3.4 — Factory caching is enabled by default in invoke tasks</summary>
+<p>Factory caching is now enabled by default with the <code>invoke unittest</code> and <code>invoke integration-test</code> commands. To bypass it, either use the <code>--no-cache-test-fixtures</code> argument to <code>invoke unittest</code> or <code>invoke integration-test</code>, or manually remove the <code>development/factory_dump.*.json</code> cache file(s).</p>
+</details>
 <div class="admonition tip">
 <p class="admonition-title">Tip</p>
 <p>Although changes to the set of migrations defined will automatically invalidate an existing factory dump, there are two other cases where you will currently need to manually remove the file in order to force regeneration of the factory data:</p>
@@ -9187,7 +9107,7 @@ If performance baselines for tests are not available:</p>
 </code></pre></div>
 <div class="admonition info">
 <p class="admonition-title">Info</p>
-<p>To output the performance evaluation to a file for later use, i.e. as performance baselines for future test runs, do <code>invoke performance-test --performance-snapshot</code>. This command will collect the <code>names</code> of the test and their <code>execution_time</code> and store them in a .yml file default to <code>report.yml</code>. Subsequently, the data in that file will have to be manually added to the baseline file set at <a href="../../user-guide/administration/configuration/optional-settings.html#test_performance_baseline_file"><code>TEST_PERFORMANCE_BASELINE_FILE</code></a> to be used as baselines in performance tests.</p>
+<p>To output the performance evaluation to a file for later use, i.e. as performance baselines for future test runs, do <code>invoke performance-test --performance-snapshot</code>. This command will collect the <code>names</code> of the test and their <code>execution_time</code> and store them in a .yml file default to <code>report.yml</code>. Subsequently, the data in that file will have to be manually added to the baseline file set at <a href="../../user-guide/administration/configuration/settings.html#test_performance_baseline_file"><code>TEST_PERFORMANCE_BASELINE_FILE</code></a> to be used as baselines in performance tests.</p>
 </div>
 <p>Example output of <code>invoke performance-test --performance-snapshot</code>:</p>
 <div class="highlight"><pre><span></span><code><a id="__codelineno-4-1" name="__codelineno-4-1" href="#__codelineno-4-1"></a><span class="p p-Indicator">-</span><span class="w"> </span><span class="nt">tests</span><span class="p">:</span>
@@ -9398,7 +9318,7 @@ If performance baselines for tests are not available:</p>
     </div>
     
     
-    <script id="__config" type="application/json">{"base": "../..", "features": ["content.code.copy", "content.tabs.link", "navigation.footer", "navigation.tabs", "navigation.tabs.sticky", "navigation.tracking", "search.highlight", "search.share", "search.suggest"], "search": "../../assets/javascripts/workers/search.07f07601.min.js", "translations": {"clipboard.copied": "Copied to clipboard", "clipboard.copy": "Copy to clipboard", "search.result.more.one": "1 more on this page", "search.result.more.other": "# more on this page", "search.result.none": "No matching documents", "search.result.one": "1 matching document", "search.result.other": "# matching documents", "search.result.placeholder": "Type to start searching", "search.result.term.missing": "Missing", "select.version": "Select version"}}</script>
+    <script id="__config" type="application/json">{"base": "../..", "features": ["content.code.copy", "content.tabs.link", "navigation.footer", "navigation.tabs", "navigation.tabs.sticky", "navigation.tracking", "search.highlight", "search.share", "search.suggest"], "search": "../../assets/javascripts/workers/search.6ce7567c.min.js", "translations": {"clipboard.copied": "Copied to clipboard", "clipboard.copy": "Copy to clipboard", "search.result.more.one": "1 more on this page", "search.result.more.other": "# more on this page", "search.result.none": "No matching documents", "search.result.one": "1 matching document", "search.result.other": "# matching documents", "search.result.placeholder": "Type to start searching", "search.result.term.missing": "Missing", "select.version": "Select version"}}</script>
     
     
       <script src="../../assets/javascripts/bundle.56dfad97.min.js"></script>