From 5d6fa52b8985f8068314aba26878a1d7d5cb84e5 Mon Sep 17 00:00:00 2001 From: Yuriy Andamasov Date: Wed, 6 May 2026 20:42:32 +0300 Subject: feat: flip swap mechanism — MD as primary, RST as override (Phase 1) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This is the first of three phases inverting the per-page swap mechanism so MD becomes the canonical primary and RST becomes the rare override. Phase 1 — file renames + conf.py exclude_patterns flip only: - Rename docs/**/md-.md to docs/**/.md (drop md- prefix) for all 254 stems previously listed in docs/_swap.txt - Rename docs/**/.rst to docs/**/rst-.rst (add rst- prefix) for the same 254 stems - Repurpose docs/_swap.txt as docs/_rst_overrides.txt; initially empty comment-only since no pages need the RST fallback right now - conf.py exclude_patterns flipped: rst-*.rst is now excluded by default instead of md-*.md - conf.py runtime-artifact references updated to _rst_override_state.json and _md_exclude.txt (Phase 2 will rewrite swap_sources.py to produce these names; for now no swap script runs because overrides list is empty) Phase 2 (next commit on this branch) will rewrite scripts/swap_sources.py with inverted rename direction, delete scripts/import_myst.py + tests, and update tests/test_swap_sources.py for the new semantics. Phase 3 will be the cleanup pass and ready-for-review flip. Generated by robots https://vyos.io --- docs/contributing/testing.rst | 197 ------------------------------------------ 1 file changed, 197 deletions(-) delete mode 100644 docs/contributing/testing.rst (limited to 'docs/contributing/testing.rst') diff --git a/docs/contributing/testing.rst b/docs/contributing/testing.rst deleted file mode 100644 index d7455103..00000000 --- a/docs/contributing/testing.rst +++ /dev/null @@ -1,197 +0,0 @@ -:lastproofread: 2025-12-02 - -.. _testing: - -####### -Testing -####### - -One of the major features introduced in VyOS 1.3 is an automated test -framework. When you assemble an ISO image, several things can go wrong. -VyOS uses this framework to detect issues before they cause downstream problems. - -This section describes how the automated testing process at VyOS works. - -Smoketests -========== - -Smoketests execute predefined VyOS CLI commands and check if the desired -daemon or service configuration is rendered. - -When an ISO image is assembled by the `VyOS CI`_, the ``BUILD_SMOKETEST`` -parameter is enabled by default. This extends the ISO configuration line -with the following packages: - -.. code-block:: python - - def CUSTOM_PACKAGES = '' - if (params.BUILD_SMOKETESTS) - CUSTOM_PACKAGES = '--custom-package vyos-1x-smoketest' - -If you plan to build your own custom ISO image and want to use VyOS's -smoketests, ensure that you have the `vyos-1x-smoketest` package installed. - -The ``make test`` command from the vyos-build_ repository launches a new -QEMU instance, and the ISO image is first installed to the virtual hard disk. - -After the first boot into the newly installed system, the main Smoketest script -is executed. It can be found at `/usr/bin/vyos-smoketest`. - -The script searches for executable test cases under -``/usr/libexec/vyos/tests/smoke/cli/`` and executes them one by one. - -.. note:: Smoketests will alter the system configuration. If you are logged - in remotely, you may lose your connection to the system. - -.. note:: To enable smoketest debugging (print the CLI set commands used), - run: ``touch /tmp/vyos.smoketest.debug``. - -Manual Smoketest Run --------------------- - -Each test is contained in its own file, so you can execute a single Smoketest -manually by running the Python test script. - -Example: - -.. code-block:: none - - vyos@vyos:~$ /usr/libexec/vyos/tests/smoke/cli/test_protocols_bgp.py - test_bgp_01_simple (__main__.TestProtocolsBGP) ... ok - test_bgp_02_neighbors (__main__.TestProtocolsBGP) ... ok - test_bgp_03_peer_groups (__main__.TestProtocolsBGP) ... ok - test_bgp_04_afi_ipv4 (__main__.TestProtocolsBGP) ... ok - test_bgp_05_afi_ipv6 (__main__.TestProtocolsBGP) ... ok - test_bgp_06_listen_range (__main__.TestProtocolsBGP) ... ok - test_bgp_07_l2vpn_evpn (__main__.TestProtocolsBGP) ... ok - test_bgp_08_zebra_route_map (__main__.TestProtocolsBGP) ... ok - test_bgp_09_distance_and_flowspec (__main__.TestProtocolsBGP) ... ok - test_bgp_10_vrf_simple (__main__.TestProtocolsBGP) ... ok - test_bgp_11_confederation (__main__.TestProtocolsBGP) ... ok - test_bgp_12_v6_link_local (__main__.TestProtocolsBGP) ... ok - test_bgp_13_solo (__main__.TestProtocolsBGP) ... ok - - ---------------------------------------------------------------------- - Ran 13 tests in 348.191s - - OK - -Interface-based tests ---------------------- - -Our smoketests not only test daemons and services, but also check if interface -configuration works as expected. There is a common base class named -``base_interfaces_test.py`` that holds all the common code for interface tests. - -These common tests consist of: - -* Add one or more IP addresses -* DHCP client and DHCPv6 prefix delegation -* MTU size -* IP and IPv6 options -* Port description -* Port disable -* VLANs (QinQ and regular 802.1q) -* ... - -.. note:: When you are working on interface configuration and want to test - if the Smoketests pass, you would normally lose the remote SSH connection - to your :abbr:`DUT (Device Under Test)`. To handle this, some interface-based - tests can be called with an environment variable beforehand to limit the - number of interfaces used in the test. By default, all interfaces (e.g., all - Ethernet interfaces) are used. - -.. code-block:: none - - vyos@vyos:~$ TEST_ETH="eth1 eth2" /usr/libexec/vyos/tests/smoke/cli/test_interfaces_bonding.py - test_add_multiple_ip_addresses (__main__.BondingInterfaceTest) ... ok - test_add_single_ip_address (__main__.BondingInterfaceTest) ... ok - test_bonding_hash_policy (__main__.BondingInterfaceTest) ... ok - test_bonding_lacp_rate (__main__.BondingInterfaceTest) ... ok - test_bonding_min_links (__main__.BondingInterfaceTest) ... ok - test_bonding_remove_member (__main__.BondingInterfaceTest) ... ok - test_dhcpv6_client_options (__main__.BondingInterfaceTest) ... ok - test_dhcpv6pd_auto_sla_id (__main__.BondingInterfaceTest) ... ok - test_dhcpv6pd_manual_sla_id (__main__.BondingInterfaceTest) ... ok - test_interface_description (__main__.BondingInterfaceTest) ... ok - test_interface_disable (__main__.BondingInterfaceTest) ... ok - test_interface_ip_options (__main__.BondingInterfaceTest) ... ok - test_interface_ipv6_options (__main__.BondingInterfaceTest) ... ok - test_interface_mtu (__main__.BondingInterfaceTest) ... ok - test_ipv6_link_local_address (__main__.BondingInterfaceTest) ... ok - test_mtu_1200_no_ipv6_interface (__main__.BondingInterfaceTest) ... ok - test_span_mirror (__main__.BondingInterfaceTest) ... ok - test_vif_8021q_interfaces (__main__.BondingInterfaceTest) ... ok - test_vif_8021q_lower_up_down (__main__.BondingInterfaceTest) ... ok - test_vif_8021q_mtu_limits (__main__.BondingInterfaceTest) ... ok - test_vif_8021q_qos_change (__main__.BondingInterfaceTest) ... ok - test_vif_s_8021ad_vlan_interfaces (__main__.BondingInterfaceTest) ... ok - test_vif_s_protocol_change (__main__.BondingInterfaceTest) ... ok - - ---------------------------------------------------------------------- - Ran 23 tests in 244.694s - - OK - -This will limit the `bond` interface test to use only `eth1` and `eth2` -as member ports. - -Config Load Tests -================= - -The other part of our tests are called "config load tests." Config load tests -sequentially load arbitrary configuration files to verify that configuration -migration scripts work as designed and that a given set of functionality can -still be loaded with a fresh VyOS ISO image. - -The configurations are all derived from production systems and can act as -test cases or as references for enabling certain features. The configurations -can be found here: -https://github.com/vyos/vyos-1x/tree/current/smoketest/configs - -The entire test is controlled by the main wrapper script -``/usr/bin/vyos-configtest``. -It behaves in the same way as the main smoketest script. It scans the folder -for potential configuration files and issues a ``load`` command for each file. - -Manual config load test ------------------------ - -You do not have to load all configurations sequentially; you can also load -individual test configurations manually. - -.. code-block:: none - - vyos@vyos:~$ configure - load[edit] - - vyos@vyos# load /usr/libexec/vyos/tests/config/ospf-small - Loading configuration from '/usr/libexec/vyos/tests/config/ospf-small' - Load complete. Use 'commit' to make changes effective. - [edit] - vyos@vyos# compare - [edit interfaces ethernet eth0] - -hw-id 00:50:56:bf:c5:6d - [edit interfaces ethernet eth1] - +duplex auto - -hw-id 00:50:56:b3:38:c5 - +speed auto - [edit interfaces] - -ethernet eth2 { - - hw-id 00:50:56:b3:9c:1d - -} - -vti vti1 { - - address 192.0.2.1/30 - -} - ... - - vyos@vyos# commit - vyos@vyos# - -.. note:: Some configurations have preconditions that must be met. These most - likely include generation of cryptographic keys before the config can be - applied; otherwise, you will get a commit error. If you are interested in - how those preconditions are fulfilled, check the vyos-build_ repository and - the ``scripts/check-qemu-install`` file. - -.. include:: /_include/common-references.txt -- cgit v1.2.3