docs: fix stale commands in binary cataloger README (#5047)

Update the binary classifier cataloger developer README to match the
current workflow:

- Testing section used the non-existent flag -must-use-full-binaries
  against .../testdata/...; the real flag is -must-use-original-binaries
  and Test_Cataloger_PositiveCases lives in the binary package. Fix the
  command and add a single-fixture variant.
- Point add-snippet references at the make target and note the (Y/n/q)
  prompt requires y to write the snippet.
- Fix the test file name (classifier_cataloger_test.go) and document the
  go generate ./internal/capabilities step for new classifiers.

Fixes #4510

Signed-off-by: alliasgher <alliasgher123@gmail.com>
This commit is contained in:
Ali Asghar 2026-07-13 20:15:01 +05:00 committed by GitHub
parent 3cc3ecb003
commit da77ea388a
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194

View File

@ -5,8 +5,9 @@
> 1. head to the correct directory: `cd testdata` > 1. head to the correct directory: `cd testdata`
> 2. add a new entry to `config.yaml` to track where to get the binary from (verify the entry with `make list`) > 2. add a new entry to `config.yaml` to track where to get the binary from (verify the entry with `make list`)
> 3. run `make download` to get the binary > 3. run `make download` to get the binary
> 4. run `make add-snippet` and follow the prompts (use `/` to search) > 4. run `make add-snippet` and follow the prompts (use `/` to search; answer `y` at the `(Y/n/q)` prompt to write the snippet)
> 5. add a new test case to `Test_Cataloger_PositiveCases` in `../cataloger_test.go` > 5. add a new test case to `Test_Cataloger_PositiveCases` in `../classifier_cataloger_test.go`
> 6. if you added a new classifier, regenerate the capabilities catalog from the repo root and commit the result: `go generate ./internal/capabilities`
To test the binary cataloger we run it against a set of files ("test fixtures"). There are two kinds of test fixtures: To test the binary cataloger we run it against a set of files ("test fixtures"). There are two kinds of test fixtures:
@ -32,7 +33,7 @@ And use tooling to list and manage the fixtures:
- `make list` - list all fixtures - `make list` - list all fixtures
- `make download` - download binaries that are not covered by a snippet - `make download` - download binaries that are not covered by a snippet
- `make download-all` - download all binaries - `make download-all` - download all binaries
- `go run ./manager add-snippet` - add a new snippet based off of a configured binary - `make add-snippet` - add a new snippet based off of a configured binary
- `capture-snippet.sh` - add a new snippet based off of a binary on your local machine (not recommended, but allowed) - `capture-snippet.sh` - add a new snippet based off of a binary on your local machine (not recommended, but allowed)
There is a `config.yaml` that tracks all binaries that the tests can use. This makes it possible to download it at any time from a hosted source. Today the only method allowed is to download a container image and extract files out. There is a `config.yaml` that tracks all binaries that the tests can use. This makes it possible to download it at any time from a hosted source. Today the only method allowed is to download a container image and extract files out.
@ -74,10 +75,17 @@ from-images:
## Testing ## Testing
The test cases have been setup to allow testing against full binaries or a mix of both (default). The test cases have been setup to allow testing against full binaries or a mix of both (default).
To force running only against full binaries run with: To force running only against the original full binaries (instead of snippets), run with the
`-must-use-original-binaries` flag:
```bash ```bash
go test -must-use-full-binaries ./syft/pkg/cataloger/binary/testdata/... go test -v ./syft/pkg/cataloger/binary -run Test_Cataloger_PositiveCases/ -must-use-original-binaries
```
To run against a single fixture, append its name to the `-run` filter:
```bash
go test -v ./syft/pkg/cataloger/binary -run Test_Cataloger_PositiveCases/<name> -must-use-original-binaries
``` ```
## Adding a new test fixture ## Adding a new test fixture
@ -91,7 +99,7 @@ Even if you are adding a snippet, it is best practice to:
1. Follow the steps above to [add a full binary](#adding-a-full-binary) 1. Follow the steps above to [add a full binary](#adding-a-full-binary)
2. Run `go run ./manager add-snippet` and follow the prompts to create a new snippet 2. Run `make add-snippet` and follow the prompts to create a new snippet (answer `y` at the `(Y/n/q)` prompt to write the snippet)
- you should see your binary in the list of binaries to choose from. If not, check step 2 - you should see your binary in the list of binaries to choose from. If not, check step 2
- if the search results in no matching snippets, you can specify your own search with `--search-for <grep-pattern>` - if the search results in no matching snippets, you can specify your own search with `--search-for <grep-pattern>`
- you should see a new snippet file created in `snippets/` - you should see a new snippet file created in `snippets/`