Coverage for apio/commands/apio_test.py: 100%

1# -*- coding: utf-8 -*- 

2# -- This file is part of the Apio project 

3# -- (C) 2016-2024 FPGAwars 

4# -- Authors 

5# -- * Jesús Arroyo (2016-2019) 

6# -- * Juan Gonzalez (obijuan) (2019-2024) 

7# -- License GPLv2 

8"""Implementation of 'apio test' command""" 

9 

10import sys 

11from typing import Optional 

12from pathlib import Path 

13import click 

14from apio.managers.scons_manager import SConsManager 

15from apio.commands import options 

16from apio.apio_context import ( 

17 ApioContext, 

18 PackagesPolicy, 

19 ProjectPolicy, 

20 RemoteConfigPolicy, 

21) 

22from apio.common.proto.apio_pb2 import ApioTestParams 

23from apio.utils import cmd_util 

24 

25 

26# --------- apio test 

27 

28 

29# -- Text in the rich-text format of the python rich library. 

30APIO_TEST_HELP = """ 

31The command 'apio test' simulates one or all the testbenches in the project \ 

32and is useful for automated testing of your design. Testbenches are expected \ 

33to have names ending with _tb (e.g., my_module_tb.v) and should exit with the \ 

34'$fatal' directive if an error is detected. 

35 

36Examples:[code] 

37 apio test # Run all *_tb.v testbenches. 

38 apio test my_module_tb.v # Run a single testbench.[/code] 

39 

40[NOTE] Testbench specification is always the testbench file path relative to \ 

41the project directory, even if using the '--project-dir' option. 

42 

43[IMPORTANT] Avoid using the Verilog '$dumpfile()' function in your \ 

44testbenches, as this may override the default name and location Apio sets \ 

45for the generated .vcd file. 

46 

47For a sample testbench compatible with Apio features, see: \ 

48https://github.com/FPGAwars/apio-examples/tree/master/upduino31/testbench 

49 

50[b][Hint][/b] To simulate a testbench with a graphical visualization \ 

51of the signals, refer to the 'apio sim' command. 

52""" 

53 

54 

55@click.command( 

56 name="test", 

57 cls=cmd_util.ApioCommand, 

58 short_help="Test all or a single verilog testbench module.", 

59 help=APIO_TEST_HELP, 

60) 

61@click.pass_context 

62@click.argument("testbench_file", nargs=1, required=False) 

63@options.env_option_gen() 

64@options.project_dir_option 

65# @options.testbench 

66def cli( 

67 _: click.Context, 

68 # Arguments 

69 testbench_file: str, 

70 # Options 

71 env: Optional[str], 

72 project_dir: Optional[Path], 

73): 

74 """Implements the test command.""" 

75 

76 # -- Create the apio context. 

77 apio_ctx = ApioContext( 

78 project_policy=ProjectPolicy.PROJECT_REQUIRED, 

79 remote_config_policy=RemoteConfigPolicy.CACHED_OK, 

80 packages_policy=PackagesPolicy.ENSURE_PACKAGES, 

81 project_dir_arg=project_dir, 

82 env_arg=env, 

83 ) 

84 

85 # -- Create the scons manager. 

86 scons = SConsManager(apio_ctx) 

87 

88 # -- Construct the test params 

89 test_params = ApioTestParams( 

90 testbench=testbench_file if testbench_file else None 

91 ) 

92 

93 exit_code = scons.test(test_params) 

94 sys.exit(exit_code)