Docs: add introduction and guide to readme #13
Conversation
There was a problem hiding this comment.
some minor changes but otherwise looking good 🎉
a quick note: I know that @lolmaus mentioned that this PR doesn't supersede #10 but we discussed it and we think it should for now. We can revisit #10 after this is merged and maybe add it as a Tutorial section, or start a docs folder at that point, but that discussion shouldn't block this PR 👍
README.md
Outdated
| Instead of defining a template project from disk as shown above, you can do it programmatically. | ||
|
|
||
| `scenario-tester` relies on [stefanpenner/node-fixturify-project](https://github.com/stefanpenner/node-fixturify-project) (npm package [fixturify-project](https://www.npmjs.com/package/fixturify-project)). |
There was a problem hiding this comment.
I think we can link to one or the other github or npm? they link back to each other so it doesn't matter which one we link to here
| ```js | ||
| project.addDependency('mocha', '5.2.0'); | ||
| project.addDependency('chai', '5.2.0'); |
There was a problem hiding this comment.
if you want to show addDependency here use fake/mock package names. These dependencies that are added have nothing to do with npm, they are created as fixturify-project Projects with a minimal setup to be considered an npm package and then added to your project
see https://github.com/embroider-build/embroider/blob/main/tests/scenarios/compat-addon-import-test.ts#L10-L32 for inspiration
README.md
Outdated
|
|
||
| ``` | ||
| cd /tmp/my-project | ||
| rm -r node_modules/ | ||
| pnpm i | ||
| ``` |
README.md
Outdated
| * `skip` — removes one scenario with the given name from collection, returns new collection; | ||
| * `only` — returns new collection containing only the scenario with the given name; | ||
| * `filter` (⚠ does not exist yet) — returns a subset of scenarios, filtered using a callback; |
There was a problem hiding this comment.
delete this line 👍 let's not document things that don't exist
README.md
Outdated
| * `--require <package-name>` — require a package before starting, e. g. `ts-node/register` if your test files are in TypeScript | ||
| * `--files <glob>` — which files to look in. | ||
| * `--matrix <format string>` — ❓ process scenario names with [util.format](https://nodejs.org/api/util.html#utilformatformat-args) and output as JSON. |
There was a problem hiding this comment.
Maybe add a section about CI setup to the guide? Maybe take from https://github.com/ef4/scenario-tester/pull/10/files#diff-b335630551682c19a781afebcf4d07bf978fb1f8ac04c6bf87428ed5106870f5R84
essentially --matrix is designed to communicate with GitHub and tell it what tests are available 👍
There was a problem hiding this comment.
I have mentioned that this flag is used in Github CI test matrix config, but have not provided full CI documentation. I suggest that it goes into docs/ along with your project setup guide.
My attempt at explaining
scenario-tester:fromProject,expandandforEachScenario, letting developers quickly grasp the idea;fixturify-projectusage for creating codebases from disk and JSON, adding dependencies to them;npm:some-npm-package--legacy@1.2.3;skip,onlyandmap;listandoutput.Rendered (only the very first paragraph pre-exists).
Corrections and additions are very welcome!
Please note that this PR does not supersede @mansona's take on readme docs in #10. Chris describes a recommended setup, more elaborate and specific than my basic guide.
#10 can be merged together with this one. The only thing I would like to change there is the title:
Getting started→Recommended setupor something like that.