nautobot 2.4.4__py3-none-any.whl → 2.4.6__py3-none-any.whl

nautobot/project-static/docs/development/core/getting-started.html

@@ -8323,36 +8323,21 @@
       <ul class="md-nav__list">
         
           <li class="md-nav__item">
-  <a href="#unit-tests" class="md-nav__link">
-    <span class="md-ellipsis">
-      Unit Tests
-    </span>
-  </a>
-  
-    <nav class="md-nav" aria-label="Unit Tests">
-      <ul class="md-nav__list">
-        
-          <li class="md-nav__item">
-  <a href="#useful-unit-test-parameters" class="md-nav__link">
+  <a href="#test-execution-examples" class="md-nav__link">
     <span class="md-ellipsis">
-      Useful Unit Test Parameters
+      Test Execution Examples
     </span>
   </a>
   
 </li>
         
           <li class="md-nav__item">
-  <a href="#unit-test-invocation-examples" class="md-nav__link">
+  <a href="#unit-tests" class="md-nav__link">
     <span class="md-ellipsis">
-      Unit Test Invocation Examples
+      Unit Tests
     </span>
   </a>
   
-</li>
-        
-      </ul>
-    </nav>
-  
 </li>
         
           <li class="md-nav__item">
@@ -8377,6 +8362,15 @@
       </ul>
     </nav>
   
+</li>
+        
+          <li class="md-nav__item">
+  <a href="#migration-tests" class="md-nav__link">
+    <span class="md-ellipsis">
+      Migration Tests
+    </span>
+  </a>
+  
 </li>
         
       </ul>
@@ -9949,36 +9943,21 @@
       <ul class="md-nav__list">
         
           <li class="md-nav__item">
-  <a href="#unit-tests" class="md-nav__link">
+  <a href="#test-execution-examples" class="md-nav__link">
     <span class="md-ellipsis">
-      Unit Tests
-    </span>
-  </a>
-  
-    <nav class="md-nav" aria-label="Unit Tests">
-      <ul class="md-nav__list">
-        
-          <li class="md-nav__item">
-  <a href="#useful-unit-test-parameters" class="md-nav__link">
-    <span class="md-ellipsis">
-      Useful Unit Test Parameters
+      Test Execution Examples
     </span>
   </a>
   
 </li>
         
           <li class="md-nav__item">
-  <a href="#unit-test-invocation-examples" class="md-nav__link">
+  <a href="#unit-tests" class="md-nav__link">
     <span class="md-ellipsis">
-      Unit Test Invocation Examples
+      Unit Tests
     </span>
   </a>
   
-</li>
-        
-      </ul>
-    </nav>
-  
 </li>
         
           <li class="md-nav__item">
@@ -10003,6 +9982,15 @@
       </ul>
     </nav>
   
+</li>
+        
+          <li class="md-nav__item">
+  <a href="#migration-tests" class="md-nav__link">
+    <span class="md-ellipsis">
+      Migration Tests
+    </span>
+  </a>
+  
 </li>
         
       </ul>
@@ -10286,7 +10274,7 @@
 <a id="__codelineno-14-15" name="__codelineno-14-15" href="#__codelineno-14-15"></a>  docker-push            Tags and pushes docker images to the appropriate repos, intended for release use only.
 <a id="__codelineno-14-16" name="__codelineno-14-16" href="#__codelineno-14-16"></a>  dumpdata               Dump data from database to db_output file.
 <a id="__codelineno-14-17" name="__codelineno-14-17" href="#__codelineno-14-17"></a>  hadolint               Check Dockerfile for hadolint compliance and other style issues.
-<a id="__codelineno-14-18" name="__codelineno-14-18" href="#__codelineno-14-18"></a>  integration-test       Run Nautobot integration tests.
+<a id="__codelineno-14-18" name="__codelineno-14-18" href="#__codelineno-14-18"></a>  lint                   Run all linters.
 <a id="__codelineno-14-19" name="__codelineno-14-19" href="#__codelineno-14-19"></a>  loaddata               Load data from file.
 <a id="__codelineno-14-20" name="__codelineno-14-20" href="#__codelineno-14-20"></a>  logs                   View the logs of a docker compose service.
 <a id="__codelineno-14-21" name="__codelineno-14-21" href="#__codelineno-14-21"></a>  makemigrations         Perform makemigrations operation in Django.
@@ -10294,18 +10282,18 @@
 <a id="__codelineno-14-23" name="__codelineno-14-23" href="#__codelineno-14-23"></a>  migrate                Perform migrate operation in Django.
 <a id="__codelineno-14-24" name="__codelineno-14-24" href="#__codelineno-14-24"></a>  migration-test         Test database migration from a given dataset to latest Nautobot schema.
 <a id="__codelineno-14-25" name="__codelineno-14-25" href="#__codelineno-14-25"></a>  nbshell                Launch an interactive Nautobot shell.
-<a id="__codelineno-14-26" name="__codelineno-14-26" href="#__codelineno-14-26"></a>  performance-test       Run Nautobot performance tests.
-<a id="__codelineno-14-27" name="__codelineno-14-27" href="#__codelineno-14-27"></a>  post-upgrade           Performs Nautobot common post-upgrade operations using a single entrypoint.
-<a id="__codelineno-14-28" name="__codelineno-14-28" href="#__codelineno-14-28"></a>  pylint                 Perform static analysis of Nautobot code.
-<a id="__codelineno-14-29" name="__codelineno-14-29" href="#__codelineno-14-29"></a>  restart                Gracefully restart containers.
-<a id="__codelineno-14-30" name="__codelineno-14-30" href="#__codelineno-14-30"></a>  ruff                   Run ruff to perform code formatting and linting.
-<a id="__codelineno-14-31" name="__codelineno-14-31" href="#__codelineno-14-31"></a>  serve-docs             Runs local instance of mkdocs serve on port 8001 (ctrl-c to stop).
-<a id="__codelineno-14-32" name="__codelineno-14-32" href="#__codelineno-14-32"></a>  showmigrations         Perform showmigrations operation in Django.
-<a id="__codelineno-14-33" name="__codelineno-14-33" href="#__codelineno-14-33"></a>  start                  Start Nautobot and its dependencies in detached mode.
-<a id="__codelineno-14-34" name="__codelineno-14-34" href="#__codelineno-14-34"></a>  stop                   Stop Nautobot and its dependencies.
-<a id="__codelineno-14-35" name="__codelineno-14-35" href="#__codelineno-14-35"></a>  tests                  Run all linters and unit tests.
-<a id="__codelineno-14-36" name="__codelineno-14-36" href="#__codelineno-14-36"></a>  unittest               Run Nautobot unit tests.
-<a id="__codelineno-14-37" name="__codelineno-14-37" href="#__codelineno-14-37"></a>  unittest-coverage      Report on code test coverage as measured by &#39;invoke unittest&#39;.
+<a id="__codelineno-14-26" name="__codelineno-14-26" href="#__codelineno-14-26"></a>  open-docs-web          Navigate to the mkdocs interface in your web browser.
+<a id="__codelineno-14-27" name="__codelineno-14-27" href="#__codelineno-14-27"></a>  open-nautobot-web      Navigate to the Nautobot interface in your web browser.
+<a id="__codelineno-14-28" name="__codelineno-14-28" href="#__codelineno-14-28"></a>  open-selenium-vnc      Navigate to the selenium VNC browser view.
+<a id="__codelineno-14-29" name="__codelineno-14-29" href="#__codelineno-14-29"></a>  post-upgrade           Performs Nautobot common post-upgrade operations using a single entrypoint.
+<a id="__codelineno-14-30" name="__codelineno-14-30" href="#__codelineno-14-30"></a>  pylint                 Perform static analysis of Nautobot code.
+<a id="__codelineno-14-31" name="__codelineno-14-31" href="#__codelineno-14-31"></a>  restart                Gracefully restart containers.
+<a id="__codelineno-14-32" name="__codelineno-14-32" href="#__codelineno-14-32"></a>  ruff                   Run ruff to perform code formatting and linting.
+<a id="__codelineno-14-33" name="__codelineno-14-33" href="#__codelineno-14-33"></a>  serve-docs             Runs local instance of mkdocs serve on port 8001 (ctrl-c to stop).
+<a id="__codelineno-14-34" name="__codelineno-14-34" href="#__codelineno-14-34"></a>  showmigrations         Perform showmigrations operation in Django.
+<a id="__codelineno-14-35" name="__codelineno-14-35" href="#__codelineno-14-35"></a>  start                  Start Nautobot and its dependencies in detached mode.
+<a id="__codelineno-14-36" name="__codelineno-14-36" href="#__codelineno-14-36"></a>  stop                   Stop Nautobot and its dependencies.
+<a id="__codelineno-14-37" name="__codelineno-14-37" href="#__codelineno-14-37"></a>  tests                  Run Nautobot automated tests.
 <a id="__codelineno-14-38" name="__codelineno-14-38" href="#__codelineno-14-38"></a>  version                Show the version of Nautobot Python package or bump it when a valid bump rule is provided.
 <a id="__codelineno-14-39" name="__codelineno-14-39" href="#__codelineno-14-39"></a>  vscode                 Launch Visual Studio Code with the appropriate Environment variables to run in a container.
 <a id="__codelineno-14-40" name="__codelineno-14-40" href="#__codelineno-14-40"></a>  yamllint               Run yamllint to validate formatting applies to YAML standards.
@@ -10643,11 +10631,38 @@
 <a id="__codelineno-41-5" name="__codelineno-41-5" href="#__codelineno-41-5"></a>Installing the current project: nautobot (1.0.0-beta.2)
 </code></pre></div>
 <h3 id="running-tests">Running Tests<a class="headerlink" href="#running-tests" title="Permanent link">&para;</a></h3>
-<p>Throughout the course of development, it's a good idea to occasionally run Nautobot's test suite to catch any potential errors. Tests come in two primary flavors: Unit tests and integration tests.</p>
+<p>Throughout the course of development, it's a good idea to occasionally run Nautobot's test suite to catch any potential errors. Tests in Nautobot come in three primary flavors: Unit tests, integration tests, and migration tests. Most commonly you'll run unit tests, integration tests less frequently, and migration tests more rarely still.</p>
 <p>For information about <strong>writing</strong> tests, refer to the <a href="testing.html">testing documentation</a>.</p>
+<p>All three types of tests are executable via the <code>invoke tests</code> (or, if using the virtual environment workflow, <code>nautobot-server test</code>) command with appropriate parameters. These commands also support many optional parameters to influence the testing behavior. Careful use of these parameters can greatly reduce the time it takes to run and re-run tests during development. Some specific examples are provided below, but for an up-to-date summary of parameters, you can always run <code>invoke tests --help</code>.</p>
+<h4 id="test-execution-examples">Test Execution Examples<a class="headerlink" href="#test-execution-examples" title="Permanent link">&para;</a></h4>
+<p>The simplest command <strong>runs all unit tests</strong> (not including integration and migration tests). This includes by default a number of performance optimizations such as <a href="testing.html#factory-caching">caching test factory data to disk</a>, keeping and reusing the database schema between successive reruns, and executing tests in parallel across available CPU cores:</p>
+<div class="highlight"><pre><span></span><code><a id="__codelineno-42-1" name="__codelineno-42-1" href="#__codelineno-42-1"></a>invoke tests
+<a id="__codelineno-42-2" name="__codelineno-42-2" href="#__codelineno-42-2"></a># functionally equivalent to explicitly setting the below flags:
+<a id="__codelineno-42-3" name="__codelineno-42-3" href="#__codelineno-42-3"></a>invoke tests --cache-test-fixtures --keepdb --buffer --parallel
+</code></pre></div>
+<p>To limit the test to a specific <strong>subset of test cases</strong> by pattern or label, you can use the <code>--label</code> or <code>--pattern</code> options. You can also instruct the test execution to <strong>stop after the first failure</strong> (if any) occurs, rather than running to completion:</p>
+<div class="highlight"><pre><span></span><code><a id="__codelineno-43-1" name="__codelineno-43-1" href="#__codelineno-43-1"></a>invoke tests --pattern Controller
+<a id="__codelineno-43-2" name="__codelineno-43-2" href="#__codelineno-43-2"></a>invoke tests --label nautobot.core.tests.dcim.test_views.DeviceTestCase
+<a id="__codelineno-43-3" name="__codelineno-43-3" href="#__codelineno-43-3"></a>invoke tests --failfast
+</code></pre></div>
+<p>Once the Nautobot static documentation has been generated once (a prerequisite for certain tests), you can <strong>skip the documentation build</strong> if you haven't made any changes to the documentation:</p>
+<div class="highlight"><pre><span></span><code><a id="__codelineno-44-1" name="__codelineno-44-1" href="#__codelineno-44-1"></a>invoke tests --skip-docs-build
+</code></pre></div>
+<p>To limit the CPU consumption on your system, you can <strong>restrict the number of parallel workers</strong> and/or <strong>run tests serially</strong>:</p>
+<div class="highlight"><pre><span></span><code><a id="__codelineno-45-1" name="__codelineno-45-1" href="#__codelineno-45-1"></a>invoke tests --parallel-workers 4
+<a id="__codelineno-45-2" name="__codelineno-45-2" href="#__codelineno-45-2"></a>invoke tests --no-parallel
+</code></pre></div>
+<p>When actively updating models or migrations, you may need to <strong>not reuse the database from the previous test run</strong>, but instead recreate it, and may also need to force <strong>regeneration of the test factory data</strong>:</p>
+<div class="highlight"><pre><span></span><code><a id="__codelineno-46-1" name="__codelineno-46-1" href="#__codelineno-46-1"></a>invoke tests --no-reusedb
+<a id="__codelineno-46-2" name="__codelineno-46-2" href="#__codelineno-46-2"></a>invoke tests --no-cache-test-fixtures
+</code></pre></div>
+<p>By default, to keep the test output concise, stdout and stderr for tests are not displayed to your terminal, and while executing, only a single character (<code>.</code> for successful tests, <code>F</code> for failures, and <code>E</code> for errors) is printed per executed test case. If you're <strong>debugging code with <code>breakpoint()</code></strong> you need to use <code>--no-buffer</code> to allow output to the terminal when a breakpoint is reached, and when troubleshooting tests in general, it may be useful to <strong>enable more verbose output from the test runner</strong>:</p>
+<div class="highlight"><pre><span></span><code><a id="__codelineno-47-1" name="__codelineno-47-1" href="#__codelineno-47-1"></a>invoke tests --no-buffer
+<a id="__codelineno-47-2" name="__codelineno-47-2" href="#__codelineno-47-2"></a>invoke tests --verbose
+</code></pre></div>
 <h4 id="unit-tests">Unit Tests<a class="headerlink" href="#unit-tests" title="Permanent link">&para;</a></h4>
 <p>Unit tests are automated tests written and run to ensure that a section of the Nautobot application (known as the "unit") meets its design and behaves as intended and expected. Most commonly as a developer of or contributor to Nautobot you will be writing unit tests to exercise the code you have written. Unit tests are not meant to test how the application behaves, only the individual blocks of code, therefore use of mock data and phony connections is common in unit test code. As a guiding principle, unit tests should be fast, because they will be executed quite often.</p>
-<p>Unit tests are run using the <code>invoke unittest</code> command (if using the Docker development environment) or the <code>nautobot-server test</code> command:</p>
+<p>Unit tests are run using the <code>invoke tests</code> command (if using the Docker development environment) or the <code>nautobot-server test</code> command:</p>
 <table>
 <thead>
 <tr>
@@ -10657,51 +10672,15 @@
 </thead>
 <tbody>
 <tr>
-<td><code>invoke unittest</code></td>
+<td><code>invoke tests</code></td>
 <td><code>nautobot-server --config=nautobot/core/tests/nautobot_config.py test nautobot</code></td>
 </tr>
 </tbody>
 </table>
 <div class="admonition info">
 <p class="admonition-title">Info</p>
-<p>By default <code>invoke unittest</code> will start and run the unit tests inside the Docker development container; this ensures that PostgreSQL and Redis servers are available during the test. However, if you have your environment configured such that <code>nautobot-server</code> can run locally, outside of the Docker environment, you may wish to set the environment variable <code>INVOKE_NAUTOBOT_LOCAL=True</code> to execute these tests in your local environment instead.</p>
+<p>By default <code>invoke tests</code> will start and run the unit tests inside the Docker development container; this ensures that PostgreSQL and Redis servers are available during the test. However, if you have your environment configured such that <code>nautobot-server</code> can run locally, outside of the Docker environment, you may wish to set the environment variable <code>INVOKE_NAUTOBOT_LOCAL=True</code> to execute these tests in your local environment instead.</p>
 </div>
-<h5 id="useful-unit-test-parameters">Useful Unit Test Parameters<a class="headerlink" href="#useful-unit-test-parameters" title="Permanent link">&para;</a></h5>
-<p>The <code>invoke unittest</code> command supports a number of optional parameters to influence its behavior. Careful use of these parameters can greatly reduce the time it takes to run and re-run tests during development.</p>
-<ul>
-<li><code>--failfast</code> - Fail as soon as any test failure or error condition is encountered, instead of running to completion.</li>
-<li><code>--label &lt;module.path&gt;</code> - Only run the specific subset of tests. Can be broad (<code>--label nautobot.core.tests</code>) or specific (<code>--label nautobot.core.tests.test_graphql.GraphQLQueryTestCase</code>).</li>
-<li><code>--no-buffer</code> - Allow stdout/stderr output from the test to be seen in your terminal, instead of being hidden. <strong>If you're debugging code with <code>breakpoint()</code>, you should use this option, as otherwise you'll never see the breakpoint happen.</strong></li>
-<li><code>--no-cache-test-fixtures</code> - Prevent caching <a href="testing.html#factory-caching">test factory data</a> to disk, or if a cache is already present, prevent loading from that cache when initializing the test environment. <strong>The <code>--no-cache-test-fixtures</code> option is mandatory if you're actively making changes to factories or model migrations.</strong></li>
-<li><code>--no-keepdb</code> - Prevent saving the initialized test database after a test run for later reuse in a test re-run.</li>
-<li><code>--no-parallel</code> - By default, Nautobot splits test execution across multiple parallel subprocesses to reduce the runtime of the test suite. When troubleshooting obscure test exceptions, it may be desirable to disable that behavior temporarily using this parameter.</li>
-<li><code>--parallel-workers</code> - Explicitly specify the number of workers to use when running tests in parallel.</li>
-<li><code>--pattern</code> - Only run tests which match the given substring. Can be used multiple times.</li>
-<li><code>--no-reusedb</code> - Prevent reusing the initialized test database from a previous test run; instead, create a new database. <strong>The <code>--no-reusedb</code> option is mandatory if you're actively making changes to model migrations, or when switching between branches that differ in their included migrations.</strong></li>
-<li><code>--skip-docs-build</code> - Skip building/rebuilding the static Nautobot documentation before running the test. Saves some time on reruns when you haven't changed the documentation source files.</li>
-<li><code>--verbose</code> - Run tests more verbosely, including describing each test case as it is run.</li>
-</ul>
-<h5 id="unit-test-invocation-examples">Unit Test Invocation Examples<a class="headerlink" href="#unit-test-invocation-examples" title="Permanent link">&para;</a></h5>
-<p>In general, when you first run the Nautobot tests in your local copy of the repository, we'd recommend:</p>
-<div class="highlight"><pre><span></span><code><a id="__codelineno-42-1" name="__codelineno-42-1" href="#__codelineno-42-1"></a>invoke unittest
-</code></pre></div>
-<p>When there are too many cores on the testing machine, you can limit the number of parallel workers:</p>
-<div class="highlight"><pre><span></span><code><a id="__codelineno-43-1" name="__codelineno-43-1" href="#__codelineno-43-1"></a>invoke unittest --parallel-workers 4
-</code></pre></div>
-<p>On subsequent reruns, you can add the other performance-related options:</p>
-<div class="highlight"><pre><span></span><code><a id="__codelineno-44-1" name="__codelineno-44-1" href="#__codelineno-44-1"></a>invoke unittest --skip-docs-build
-<a id="__codelineno-44-2" name="__codelineno-44-2" href="#__codelineno-44-2"></a>invoke unittest --skip-docs-build --label nautobot.core.tests
-</code></pre></div>
-<p>When switching between significantly different branches of the code base (e.g. <code>main</code> vs <code>develop</code> vs <code>next</code>), you'll need to for once include the <code>--no-keepdb</code> option so that the test database can be destroyed and recreated appropriately:</p>
-<div class="highlight"><pre><span></span><code><a id="__codelineno-45-1" name="__codelineno-45-1" href="#__codelineno-45-1"></a>invoke unittest --no-keepdb
-</code></pre></div>
-<p>To not use the cached test fixture, you will need to include the <code>--no-cache-test-fixtures</code> flag</p>
-<div class="highlight"><pre><span></span><code><a id="__codelineno-46-1" name="__codelineno-46-1" href="#__codelineno-46-1"></a>invoke unittest --no-cache-test-fixtures
-</code></pre></div>
-<p>To limit the test to a specific pattern or label, you can use the <code>--label</code> and <code>--pattern</code> options:</p>
-<div class="highlight"><pre><span></span><code><a id="__codelineno-47-1" name="__codelineno-47-1" href="#__codelineno-47-1"></a>invoke unittest --verbose --skip-docs-build --label nautobot.core.tests.dcim.test_views.DeviceTestCase
-<a id="__codelineno-47-2" name="__codelineno-47-2" href="#__codelineno-47-2"></a>invoke unittest --verbose --skip-docs-build --pattern Controller
-</code></pre></div>
 <h4 id="integration-tests">Integration Tests<a class="headerlink" href="#integration-tests" title="Permanent link">&para;</a></h4>
 <p>Integration tests are automated tests written and run to ensure that the Nautobot application behaves as expected when being used as it would be in practice. By contrast to unit tests, where individual units of code are being tested, integration tests rely upon the server code actually running, and web UI clients or API clients to make real connections to the service to exercise actual workflows, such as navigating to the login page, filling out the username/passwords fields, and clicking the "Log In" button.</p>
 <p>Running integrations tests requires the use of Docker at this time. They can be directly invoked using <code>nautobot-server test</code> just as unit tests can, however, a headless Firefox browser provided by Selenium is required. Because Selenium installation and setup is complicated, we have included a configuration for this to work out of the box using Docker.</p>
@@ -10721,11 +10700,7 @@
 </tr>
 </tbody>
 </table>
-<p>Integration tests are run using the <code>invoke integration-test</code> command. All integration tests must inherit from <code>nautobot.core.testing.integration.SeleniumTestCase</code>, which itself is tagged with <code>integration</code>. A custom test runner has been implemented to automatically skip any test case tagged with <code>integration</code> by default, so normal unit tests run without any concern. To run the integration tests the <code>--tag integration</code> argument must be passed to <code>nautobot-server test</code>.</p>
-<details class="version-changed">
-<summary>Changed in version 2.0.0</summary>
-<p><code>SeleniumTestCase</code> was moved from the <code>nautobot.utilities.testing.integration</code> module to <code>nautobot.core.testing.integration</code>.</p>
-</details>
+<p>Integration tests are run by passing <code>--tag integration</code> to the <code>invoke tests</code> command. All other optional parameters to this command can be used the same as with unit tests.</p>
 <table>
 <thead>
 <tr>
@@ -10735,22 +10710,14 @@
 </thead>
 <tbody>
 <tr>
-<td><code>invoke integration-test</code></td>
+<td><code>invoke tests --tag integration</code></td>
 <td><code>nautobot-server --config=nautobot/core/tests/nautobot_config.py test --tag integration nautobot</code></td>
 </tr>
 </tbody>
 </table>
-<div class="admonition info">
-<p class="admonition-title">Info</p>
-<p>The same arguments supported by <code>invoke unittest</code> are supported by <code>invoke integration-test</code>, with the exception of <code>--parallel</code> at this time. The key difference being the dependency upon the Selenium container, and inclusion of the <code>integration</code> tag.</p>
-</div>
-<div class="admonition tip">
-<p class="admonition-title">Tip</p>
-<p>You may also use <code>invoke integration-test</code> in the Virtual Environment workflow given that the <code>selenium</code> container is running, and that the <code>INVOKE_NAUTOBOT_LOCAL=True</code> environment variable has been set.</p>
-</div>
 <div class="admonition tip">
 <p class="admonition-title">Tip</p>
-<p>The <code>--cache-test-fixtures</code> argument was added to the <code>invoke integration-test</code> and <code>nautobot-server test</code> commands to allow for caching of test factory data between test runs. See the <a href="testing.html#factory-caching">factories documentation</a> for more information.</p>
+<p>You may also use <code>invoke tests --tag integration</code> in the Virtual Environment workflow given that the <code>selenium</code> container is running, and that the <code>INVOKE_NAUTOBOT_LOCAL=True</code> environment variable has been set.</p>
 </div>
 <h5 id="customizing-integration-test-executions">Customizing Integration Test Executions<a class="headerlink" href="#customizing-integration-test-executions" title="Permanent link">&para;</a></h5>
 <p>The following environment variables can be provided when running tests to customize where Nautobot looks for Selenium and where Selenium looks for Nautobot. If using the default setup documented above, there is no need to customize these.</p>
@@ -10758,6 +10725,10 @@
 <li><code>NAUTOBOT_SELENIUM_URL</code> - The URL used by the Nautobot test runner to remotely control the headless Selenium Firefox node. You can provide your own, but it must be a <a href="https://selenium-python.readthedocs.io/getting-started.html#using-selenium-with-remote-webdriver"><code>Remote</code> WebDriver</a>. (Default: <code>http://localhost:4444/wd/hub</code>; for Docker: <code>http://selenium:4444/wd/hub</code>)</li>
 <li><code>NAUTOBOT_SELENIUM_HOST</code> - The hostname used by the Selenium WebDriver to access Nautobot using Firefox. (Default: <code>host.docker.internal</code>; for Docker: <code>nautobot</code>)</li>
 </ul>
+<h4 id="migration-tests">Migration Tests<a class="headerlink" href="#migration-tests" title="Permanent link">&para;</a></h4>
+<p>Migration tests are automated tests of Nautobot database migrations, used to validate software upgrade (and rarely downgrade) scenarios. Because of their relatively slow performance, and because data migrations are rarely changed once initially written and validated, <em>migration tests do not run by default</em>, even in Nautobot's continuous integration (CI) environment, and <strong>must be run manually when relevant</strong>.</p>
+<p>Migration tests are run by passing <code>--tag migration_test</code> to the <code>invoke tests</code> command. All other optional parameters to this command can be used the same as with unit tests.</p>
+<p>See <a href="#handling-migrations">below</a> for more best practices when developing and testing migrations.</p>
 <h3 id="verifying-the-rest-api-schema">Verifying the REST API Schema<a class="headerlink" href="#verifying-the-rest-api-schema" title="Permanent link">&para;</a></h3>
 <p>If you make changes to the REST API, you should verify that the REST API OpenAPI schema renders correctly without errors. To verify that there are no errors, you can run the <code>invoke check-schema</code> command (if using the Docker development environment) or the <code>nautobot-server spectacular</code> command. In the latter case you should run the command for each supported REST API version that Nautobot provides (e.g. "2.0", "2.1")</p>
 <table>
@@ -10836,7 +10807,7 @@
 <p>You’ll also want to run <code>invoke ruff --autoformat</code> (or <code>ruff format</code>) against the generated migration file as the autogenerated code doesn’t follow our style guide by default.</p>
 <p>When modifying model field attributes, modify the test data in the tests too to reflect these changes and also any forms which refer to the model.</p>
 <h4 id="testing-migrations">Testing Migrations<a class="headerlink" href="#testing-migrations" title="Permanent link">&para;</a></h4>
-<p>Nautobot includes a number of data sets under the <code>development/datasets/</code> directory that represent various snapshots of historical database contents. You should validate whether your migrations correctly and successfully handle these datasets by running the <code>invoke migration-test --db-engine [postgres|mysql] --dataset development/datasets/&lt;filename&gt;</code> command (which handles both the Docker Compose workflow as well as the Virtual Environment workflow).</p>
+<p>In addition to the automated <a href="#migration-tests">migration tests</a> described above, Nautobot includes a number of data sets under the <code>development/datasets/</code> directory that represent various snapshots of historical database contents. You should validate whether your migrations correctly and successfully handle these datasets by running the <code>invoke migration-test --db-engine [postgres|mysql] --dataset development/datasets/&lt;filename&gt;</code> command (which handles both the Docker Compose workflow as well as the Virtual Environment workflow).</p>
 <h2 id="working-on-documentation">Working on Documentation<a class="headerlink" href="#working-on-documentation" title="Permanent link">&para;</a></h2>
 <p>Some features require documentation updates or new documentation to be written. The documentation files can be found in the <code>docs</code> directory. To preview these changes locally, you can use <code>mkdocs</code>.</p>
 <p>For substantial changes to the code (including new features, removal of existing features, or significant changes in behavior) you should always make corresponding documentation updates. Nautobot's documentation pipeline includes a custom plugin for <code>mkdocs</code> that adds a few useful macros for annotating such changes:</p>

nautobot/project-static/docs/development/core/release-checklist.html

@@ -9723,7 +9723,7 @@ To create the tag locally:</p>
 <div class="highlight"><pre><span></span><code><a id="__codelineno-19-1" name="__codelineno-19-1" href="#__codelineno-19-1"></a>for ver in 3.9 3.10 3.11 3.12; do
 <a id="__codelineno-19-2" name="__codelineno-19-2" href="#__codelineno-19-2"></a>  export INVOKE_NAUTOBOT_PYTHON_VER=$ver
 <a id="__codelineno-19-3" name="__codelineno-19-3" href="#__codelineno-19-3"></a>  invoke stop
-<a id="__codelineno-19-4" name="__codelineno-19-4" href="#__codelineno-19-4"></a>  invoke integration-tests
+<a id="__codelineno-19-4" name="__codelineno-19-4" href="#__codelineno-19-4"></a>  invoke tests --tag integration
 <a id="__codelineno-19-5" name="__codelineno-19-5" href="#__codelineno-19-5"></a>done
 </code></pre></div>
 <p>Push the images to GitHub Container Registry and Docker Hub</p>

nautobot/project-static/docs/development/core/style-guide.html

@@ -9436,7 +9436,7 @@
 <a id="__codelineno-1-5" name="__codelineno-1-5" href="#__codelineno-1-5"></a>invoke pylint
 </code></pre></div>
 <p>or, as a single command:</p>
-<div class="highlight"><pre><span></span><code><a id="__codelineno-2-1" name="__codelineno-2-1" href="#__codelineno-2-1"></a>invoke tests --lint-only
+<div class="highlight"><pre><span></span><code><a id="__codelineno-2-1" name="__codelineno-2-1" href="#__codelineno-2-1"></a>invoke lint
 </code></pre></div>
 <h2 id="introducing-new-dependencies">Introducing New Dependencies<a class="headerlink" href="#introducing-new-dependencies" title="Permanent link">&para;</a></h2>
 <p>The introduction of a new dependency is best avoided unless it is absolutely necessary. For small features, it's generally preferable to replicate functionality within the Nautobot code base rather than to introduce reliance on an external project. This reduces both the burden of tracking new releases and our exposure to outside bugs and attacks.</p>