This was previously typed as any - JestTestRunner is just a type alias for any at this point, but I saved that piece of tech debt for another day - https://github.com/ionic-team/stencil/pull/4883/files#diff-4b0dc677b3f6e55c5f547f5585915852d874a4a1ff77a6211becc016251521fcR38-R39

Importing from @stencil/core or another subdirectory, the test.dist scripts begin to fail. I'm kicking the can down the road a little here on that, in case a better design reveals itself as I work on v28+ implementatons

There's minimal JSDoc in this file, as it's expected that they (the docs) are inherited by the ABC (unless there's a good reason to override/append to the the JSDoc, then that should be called out)

I thought maybe this would be able to resolve the "adapter" based on consistent file structure and naming conventions (and a default export from the file). That too magical?

The original prototype actually used something very similar to what you're describing:

class Jest27StencilAdapter extends JestFacade {
  static override async getRunner() {
    return await import('./experimental/jest-27-and-under/jest-runner');
  }
  static override async getScreenshot() {
    return await import('./experimental/jest-27-and-under/jest-screenshot');
  }
}

I found there were a couple shortcomings with this:

1. Type safety wasn't as "nice" as I wanted it to be (the return type of getRunner is a Promise<> that returns the shape of whatever the export of jest-runner is). I found this to be kind of annoying to work with/harder to understand
2. It introduced async/await to the the whole call chain, which wasn't strictly necessary
3. Refactoring (say for instance, I were to hoist 'jest-27-and-under' out of that 'experimental' directory 😉) wasn't very pleasurable either.

By using the Facade pattern in this way, we can be super explicit about what adapters/implementations map to which versions of Jest, avoid some async/await overhead, and have some better (IMO) refactoring ability.

Just curious, where did the term "facade" come from for these when we use "adapter" for the actual implementations and definitions?

"Facade" comes from our use of the Facade Pattern here - adapter isn't quite right in terms of a classic Gang of Four pattern, but I renamed things so many times that it probably "just made sense" to me at the time. I'll rename these a bit for some better....well, to be better 😆

Okay, I think I made this a little more cohesive in 2ac845e - LMK what you think

Should this pull directly from the the v27 adapter rather than the abstract one? I know it evaluates to the same thing, but that would keep the version-specific adapters from "knowing about" the more generic stuff

I'm not sure - my only concern here is that the general version has a cache of the adapter, whereas the version specific versions don't. Let me verify this won't run >1 for npx stencil test and I'll circle back

Mkay - we can do this 👍 Verified that this isn't called >1, so we don't end up instantiating a new Facade instance each time we test. Updated in 615402c

Another spot where it'd be nice if the abstract layer didn't need to worry about version-specific APIs. Anything we can do with generics here? How are these types consumed?

Another spot where it'd be nice if the abstract layer didn't need to worry about version-specific APIs.

Trust me, I wish we could 😆 The problem is that the generic version of our connectors/adapters need to return something. And those something's need to be compatible with Jest.

Anything we can do with generics here? How are these types consumed?

Right now, they're only used by jest-adapter.ts. I think in the near future, we'll end up refactoring this to be less aware of these types. But the exact shape/form hasn't "presented itself" yet - I have a feeling once we get Jest 28 in place, that'll start to become more evident

j/w, are there any advantages / disadvantages either way between the approaches of having an ABC and implementations that extend it (a là JEst27Stencil here) vs an interface that the actual implemetations then implement? classes with the abstract keyword do actually have a runtime representation and can have concrete methods on them - right now it looks like the JestFacade doesn't have any concrete / non-abstract methods on it so would basically be class JestFacade { } after compilation.

Did you give any thought to using an interface to constrain the shape of the facade classes (like Jest27Stencil here) instead of an ABC? Maybe we will need to have some behavior on the base class in the future

anyway just sort of thinking through this as I read the PR

I did give it some thought, and originally had gone the ABC route because I did have a few concrete implementations in the base class here - but those have obviously been removed since then (hence your question). It's relatively trivial to convert between the two. I say let's go with an interface for now unless we find we really need it later down the road. Done in 4327cfc