[Bro-Dev] Testing and Docs for Packages

[Jan Grashöfer]

> Yes, seems useful.  I’d do it like:
> 
> 1) Add `bro-pkg test <package>` command.
> 2) Add “test_command” field to bro-pkg.meta
> 
> The “test_command” is more general than “test_dir" — the command could just `cd test_dir` if needed and there’s no other reason bro-pkg needs to know the dir where tests are stored, is there?

Although I am not sure whether this degree of flexibility is really
needed, I would assume it doesn't hurt either. In any way, the user
should be informed that "something" will be executed and the user should
trust the packet author/source.

> 1) Is it fine for `bro-pkg test <package>` to operate on the installed version of the package or are there expectations of testing a package in an isolated sandbox without installing it?  I think the former is more useful since it may catch odd inter-package conflicts that wouldn’t show up when testing in isolation.

I think testing on the installed version is fine. Installation might be
in particular necessary for packages containing plugins.

> 2) Should we put btest on PyPi, add it as a dependency to bro-pkg, and make it the canonical testing framework for packages?  This gives devs a straightforward way to proceed w/ writing tests and guarantees that bro-pkg users always have the ability to run them.

Ha, I forgot that bro-pkg is published using PyPi. Adding btest as a
dependency sounds great to me.

> If the problem is that there’s a lack of examples/templates for generating script API docs via broxygen or that it simply doesn’t work at the moment, then yes, that’s something to fix.

Looking at https://www.bro.org/development/howtos/autodoc.html, I wasn't
able to generate anything for my custom script. Looking into the Bro
code I could deduce the meaning of the broxygen.conf values and was able
to generate reST. I didn't try to generate HTML. A 3-step guide how to
generate doc for a custom script using the HTML template would be great.

> But regarding the direction of autogenerated package docs in general, maybe it makes sense to work on that in conjunction with a web-frontend for package sources (e.g. a package repository browser).

Cool! I wasn't aware that a web-frontend is on the list. In that case,
any autogeneration of docs is indeed something to consider in this context.

Best regards,
Jan