QADOCS tool use guide

How to use qa-docs tool

After installing qa-docs(you can follow the installation guide steps), you can check the qa-docs help.

• -h, --help: Print the qa-docs help message.
• --sanity-check: Perform a sanity check using the data previously parsed. Tests coverage, errors, and tests count.
• -v, --version: Print the qa-docs version.
• --no-logging: Disable qa-docs logging.
• -d, --debug: Run in debug mode.
• -p, --tests-path: Specify the path of the tests to be parsed. Set it when you want to parse or run a sanity check.
• -t, --types: Parse the tests from type(s) that it is passed as an argument.
• -c, --components: Parse the tests from type(s) that it is passed as an argument.
• -s, --suites: Parse the tests from type(s) that it is passed as an argument.
• -m, --modules: Parse the tests from module(s) that it is passed as an argument.
• -o: Select the output directory where the documentation will be generated.
• --format: Select the generated files format. Set as JSON by default.
• -e, --exist: Check if the given test(s) exist(s).
• --check-documentation: Check if the modules(s) passed with -m is(are) documented following the current qa-docs schema.
• --validate-parameters: Validate the parameters passed to the qa-docs tool.
• -i: Index the data previously parsed.
• -l: Launch search-uiwith the data previously indexed.
• -il: Index the data previously parsed and launch search-ui
• --docker-run: Run a docker container that runs qa-docs with the same arguments that it receives. This allows you to run qa-docs as you would do in a local environment.
• --qa-branch: Specifies the branch that allocates the tests input when --docker-run is passed.

Parameter restrictions

• --types, --components, --suites, --modules, --exist and --sanity-check need the -p option.
• -e cannot be launched with --types and --modules, -i, -l and -il options.
• --check-documentation only allows runs with the -m option.
• --qa-branch only allows runs with the --docker-run option.

Examples:

Parse all the tests within the path.

qa-docs --tests-path /tmp/wazuh-qa/tests

Parse integration tests

qa-docs --tests-path /tmp/wazuh-qa/tests --types integration

Parse test_active_response and test_agentd components

qa-docs --tests-path /tmp/wazuh-qa/tests --types integration --components test_active_response test_agentd

Parse config and rbac suites from api component

qa-docs --tests-path /path-to-tests/ --types integration --components test_api --suites test_config test_rbac

Parse some modules from logtest configuration suite

qa-docs --tests-path /path-to-tests/ --types integration --components test_logtest --suites test_configuration --modules test_configuration_file test_get_configuration_sock

Check if some modules exist

qa-docs --tests-path /path-to-tests/ --types integration --components test_logtest --suites test_configuration --exist test_configuration_file test_get_configuration_sock

Parse some modules and select the custom output directory

qa-docs --tests-path /path-to-tests/ --types integration --components test_logtest --suites test_configuration --modules test_configuration_file test_get_configuration_sock -o /tmp/logtest_cfg

Check if some logtest modules has documentation blocks

qa-docs -p /path-to-tests/ --types integration --components test_logtest --suites test_configuration --modules test_configuration_file test_get_configuration_sock --check-documentation

Create an index with the data previously parsed

qa-docs -i index_name

Launch search-ui the data previously indexed via web browser

qa-docs -l index_name

Index the data previously parsed and launch search-ui

qa-docs -il index_name

Parse integration tests components, index the data and launch search-ui to visualize it via web browser

qa-docs --tests-path /tmp/wazuh-qa/tests --types integration --components test_active_response test_agentd -il index_name

Parse integration tests components, index the data and launch search-ui to visualize it via web browser(using YAML format)

qa-docs --tests-path /tmp/wazuh-qa/tests --types integration --components test_active_response test_agentd -il index_name --format yaml

Perform a sanity check after a previous parse run

qa-docs --tests-path /tmp/wazuh-qa/tests --sanity-check

Parse test_active_response tests and generate the documentation in /tmp/qa_docs using Docker

qa-docs --docker-run --qa-branch 1796-migrate-doc-active-response --types integration --components test_active_response

Parse test_fim tests and generate the documentation in custom output path using Docker

qa-docs --docker-run --qa-branch 1796-migrate-doc-active-response --types integration --components test_fim -o /custom/path

Parse test_active_response tests and launch search-ui to visualize the documentation using Docker

qa-docs --docker-run --qa-branch 1796-migrate-doc-active-response --types integration --components test_active_response -il qa-index

More details and examples can be found in the qa-docs README.MD.