excellent examples pull in Pepr dist folder to test new api functionality

[cmwylie19]

Is your feature request related to a problem? Please describe.

When there are changes to the surface of the Pepr api, excellent examples is not able to be run against them in CI until the branch is pulled into main.

export async function moduleBuild({ version = "", verbose = false } = {}) {
  // can't have await expressions in default args, so gotta do it here
  if (version === "") { version = await peprVersion() }

  // pepr cmds use default tsconfig.json (NOT the cli's tsconfig.json)
  const pepr = { TS_NODE_PROJECT: "" }

  let cmd = `npx --yes pepr@${version} build`
  console.time(cmd)
  const build = await new Cmd({ env: pepr, cmd }).run()
  if (verbose) { console.log(build) }
  console.timeEnd(cmd)
}

Describe the solution you'd like

• Given we are running the e2e in ci against a PR candidate not merged into main
• When we build the module moduleBuild
• Then the candidate branch is cloned, build, and the dist folder is copied to the excellent examples

Describe alternatives you've considered

(optional) A clear and concise description of any alternative solutions or features you've considered.

Additional context

Add any other context or screenshots about the feature request here.

[btlghrants]

I'm not 100% that this would be better than just symlinking pepr --> pepr-excellent-examples/node_modules/pepr as we've been doing manually. :thinking:

moduleBuild is called for every excellent example which means that an update as described would do a separate clone & build every time, which... would not be awesome. I suspect it'd be easier / faster to just add the symlinking as a distinct step before we ran the test suite in CI, no?

[samayer12]

A manual workaround for developers is included as part of pepr-excellent-examples. I'll consider both approaches as I work on this

[btlghrants]

I think that just formalizing the manual workaround would be for the best, honestly.

Trying to change moduleBuild() do that stuff just means we'll be wasting a bunch of time / cycles cloning / building over and over (once for every excellent example run, at least); would introduce the possibility that git can have issues that spill into the test runs (like having config / credential issues); would require a connection to GitHub for the tests to run, and so on.

I think its better to just assume / aim for a situation where -- by the time the tests run (anything after npm run test:e2e) -- should not pull remote anything / should expect that all the test-required resources are already in place (something that just symlinking pepr would handle cleanly). Anything else just introduces risk that we don't need, IMO.

[samayer12]

After some review, the best option seems to be using the approach taken by tests in journey/ that run npx --yes ${peprAlias} where peprAlias points to pepr-0.0.0-development.tgz (the thing we're trying to test). This way, we can avoid messing with symlinks as referenced in the excellent-examples readme while also avoiding the same repeated setup action in a function like moduleBuild().

I ran into some issues with file path references that ate up a lot of time, so a usable solution shouldn't be as brittle as things are right now.

For reference:

• PR to pepr-excellent-examples
• PR to pepr
• CI job logs for passing proof of concept for a simple excellent-example

[samayer12]

In CI, we can just provide the build-under-test with an npx command.

Locally, we've favored a symlink-based approach. Both approaches could work (i.e., symlink to a directory during test setup or copy a .tgz archive during test setup). The best place for this setup so that it only runs once every time we trigger the test suite looks like _hepers/dev/cli.mts by way of a preAction & postAction hook.

[samayer12]

The test suite will probably support 3 behaviors when testing the pepr CLI package:

• default: Use pepr version defined in node_modules. Current behavior.
• --local-package: Build a pepr CLI package locally and use it for tests. Good for local testing when you're modifying pepr frequently.
• --custom-package: Use a provided pepr CLI package for tests. Good for CI when pepr is already built by an earlier step.

Example usages would look something like: npm run test:e2e -w $EXCELLENT_EXAMPLE npm run test:e2e -w $EXCELLENT_EXAMPLE -- --local-package npm run test:e2e -w $EXCELLENT_EXAMPLE -- --custom-package ../my-pepr.tgz