[Proposal] Load YAML anchors declared in external YAML files

[h6ah4i]

I have contributed a PR to enable YAML anchors and aliases in runn. Now, I want to empower the anchors and aliases feature more with the following feature that goccy/go-yaml provides. If we can use the feature effectively, we can write runbooks more DRY way.

2. Reference elements declared in another file
   https://github.com/goccy/go-yaml?tab=readme-ov-file#2-reference-elements-declared-in-another-file

---

[Draft] Specs.

• Add --yaml-references command line option that specifies where to load yaml files that define anchors globally
  • ex.) runn run --yaml-references ./references/**/*.yml ./books/**/*.yml
• Use the ReferenceReaders() function
  • We can apply the runn's read:parent policy before passing the contents
  • We can use the same glob syntax like testdata/references/**/*.yml

[k1LoW]

@h6ah4i Thank you for your proposal!

I think this is a very interesting proposal.
However, I do not see any strong reason to introduce it at this time.

1. The ability to reference other files is not an inherent feature of YAML.
2. runn has Include runner. Some of what you want to achieve with the include runner may be possible.
3. runn has the ability to expand environment variables. Some of what you want to achieve with the variable expansion feature may be possible. It will work especially well with anchors and aliases.
4. Some of what you want to achieve can be accomplished by concatenating the runbook with a reference YAML file in the tmp directory before the runn is executed. It will work especially well with anchors and aliases.

This is my opinion, and I also believe that in the context of testing, it should not be too DRY. I think the features of anchors and aliases should be sufficient.

[h6ah4i]

Thank you for reply 🙇‍♂️

1. The ability to reference other files is not an inherent feature of YAML.

Exactly. This is also my biggest concern.

2. runn has Include runner. Some of what you want to achieve with the include runner may be possible.
3. runn has the ability to expand environment variables. Some of what you want to achieve with the variable expansion feature may be possible. It will work especially well with anchors and aliases.
4. Some of what you want to achieve can be accomplished by concatenating the runbook with a reference YAML file in the tmp directory before the runn is executed. It will work especially well with anchors and aliases.

This is my opinion, and I also believe that in the context of testing, it should not be too DRY. I think the features of anchors and aliases should be sufficient.

You are totally right too, tests should not be too DRY and the technics 2, 3 and 4 are good practices for reducing duplication of runbook contents.

The technic 4 seems like the closest thing to what I want to do, but this approach can be a huge pain if you have so many runbooks. (I am already use the technics 2 and 3.)

Situations where I would like to use the --yaml-references option are only the followings for now. These are not main interest of the tests, but I have to write them over and over again.

1. Sharing db/api runner declarations used in every runbooks
2. Sharing common API request headers used in every runbooks (and used multiple times in a runbook)

[k1LoW]

Thank you!!

I do not want to put additional features directly into runn's YAML processing. I wish there was another way to do more.

If you want to make runbooks more DRY, you may want to consider using runn as a package.

1. Sharing db/api runner declarations used in every runbooks

I have solved this by writing code that reads using runn.Runner option.

Or the --runner option might work.

2. Sharing common API request headers used in every runbooks (and used multiple times in a runbook)

runn.Var option could be used.

[h6ah4i]

Yes, using runn as a Go's test helper package offers great flexibility. Even so, I love using runn as a standalone tool because it's still powerful and very handy.

Or the --runner option might work.

Thanks, I have not noticed the option! But unfortunately, it seems that it only supports runner without options (non map form in YAML format). It would be nice if we can specify YAML file(s) that contains runner setups in runbook format instead.

[h6ah4i]

2. Sharing common API request headers used in every runbooks (and used multiple times in a runbook)

On second thought, this scenario can be covered if HTTP runner have a global-headers option mentioned in #619.