exercism / exercism/configlet

Tests: Test or remove `runnableExamples` in non-exported procs

Open
#97 0 comments 1 reaction 0 assignees View on GitHub
kind: tests
Dominant language
Nim
Stars
23
Forks
17
Avg merge
13h 57m
Merged PRs (30d)
1

Description

PR https://github.com/exercism/canonical-data-syncer/pull/94 added some `runnableExamples` to a non-exported proc, which means that the examples don't run even if we were to add `nim doc` to the CI.

It would be nice to have:
- the benefits of having examples right next to the implementation of non-exported procs
- and keep those examples tested.

@ee7 wrote:
> The alternatives that I'm aware of:
>
> 1. Remove the examples entirely, but then the documentation is less clear.
> 2. Turn the `runnableExamples` into doc comments, but then they're harder to test and thus keep in-sync with the code.
> 3. Move the examples into `when isMainModule` tests, and add `nim c -r cli.nim` to the CI workflow. This means that they're tested, but the documentation suffers because the examples aren't close to the func itself, and the test layout becomes more convoluted.
> 4. Move the examples into a new file in the `tests` directory. This requires using `include cli` (rather than `import`), or a short hack/macro to export non-exported procs for testing purposes.
> 5. Export the func, but that signals to the reader that the func is used outside the `cli.nim` file, which it isn't.

Contributor guide

No contributing guide indexed for this repository

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.