Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Docs: add introduction and guide to readme #13

Merged
merged 2 commits into from
Sep 1, 2023

Conversation

lolmaus
Copy link
Contributor

@lolmaus lolmaus commented Aug 2, 2023

My attempt at explaining scenario-tester:

  • starts with a definition of a problem;
  • then explains the solution in high-level phrasing;
  • provides code samples for basic usage with fromProject, expand and forEachScenario, letting developers quickly grasp the idea;
  • explains fixturify-project usage for creating codebases from disk and JSON, adding dependencies to them;
  • explains how to add different versions of the same dependency: npm:[email protected];
  • explains reusing an customizing scenarios with skip, only and map;
  • documents CLI: list and output.

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 startedRecommended setup or something like that.

Copy link
Member

@mansona mansona left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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)).
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done.

```js
project.addDependency('mocha', '5.2.0');
project.addDependency('chai', '5.2.0');
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Changed.

README.md Outdated
Comment on lines 139 to 145

```
cd /tmp/my-project
rm -r node_modules/
pnpm i
```
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

delete this section 👍

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done.

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;
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

delete this line 👍 let's not document things that don't exist

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Removed.

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.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 👍

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

@mansona mansona self-assigned this Aug 22, 2023
Copy link
Member

@mansona mansona left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM

@mansona mansona merged commit a5898f4 into embroider-build:main Sep 1, 2023
@mansona mansona added the documentation Improvements or additions to documentation label Sep 4, 2023
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
documentation Improvements or additions to documentation
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants