search

chaijs / chaijs.github.io

The chaijs.com website source code. Contributions welcome.
http://chaijs.github.io
49 stars 71 forks source link

Update docs for chai 5 - ESM #205

Open schrotie opened 6 months ago

schrotie commented 6 months ago

As discussed here I open an issue for updating Chai's docs since Chai is now using ESMs exclusively and following the docs will break for people using it in a browser.

I've done a little work on that and created a patch. I don't fork and create a PR because I don't have a ruby environment set up and can thus not verify my changes. Github apparently does not support attaching *.patch here. Would you like me to paste the patch here?

keithamus commented 5 months ago

You can go ahead and paste the patch here, and we can look at applying it. Thanks!

schrotie commented 5 months ago

Okay, quick summary:

I stumbled upon the problem in the browser, so that's my perspective. I looked through https://www.chaijs.com/ and tried to find the stuff there in the source and fix it. I went through the guides. I also looked through the plugins, started, but realized that one needs to know the names of the exports of all the plugin. Fixing the plugins docs will be quite some work ...

I always use import {x} from 'chaijs' because I think that's cleaner. I think this works in node without additional hoop jumping but in the browser that requires building or an importmap which I documented in 'installation'. The alternative would be import {x} from../node_modules/chai/chai.js` - and that path depends on where you are, or an absolute path depends on where your root is.

Related to this: I did not use the chai/register-should set up. It's possible (and easy) but requires additional set up in the importmap so I decided skipping the latter and instead adding a line for calling should() is simpler. However, for node-users chai/register-should would indeed still save a line, but I did not spend the thought on how to integrate that into the docs. See this comment.

Next comment is the patch.

Thanks for making and maintaining Chai!

schrotie commented 5 months ago 
diff --git a/_guides/installation.md b/_guides/installation.md
index 167b47e..de6dd2b 100644
--- a/_guides/installation.md
+++ b/_guides/installation.md
@@ -39,18 +39,28 @@ which can be especially powerful when paired with a continuous integration tool.

 Include the chai browser build in your testing suite.

-```html
-<script src="chai.js" type="text/javascript"></script>
+```javascript
+import {assert, expect, should} from 'chai';

-This will provide chai as a global object, or define it if you are using AMD. +This will provide chai's assertion utilities in your ESModule. You'll likely +want to select one of these. + +If you are working in a browser without a build step, you'll need to tell the +browser where to find chai, e.g.: + +```HTML + +```

The latest tagged version will be available for hot-linking at http://chaijs.com/chai.js. If you prefer to host yourself, use the chai.js file from the root of the github project. We recommend that you always use a version tag as your starting point, so the tag download list is the best place to start.

-Currently supports all modern browsers: IE 9+, Chrome 7+, FireFox 4+, Safari 5+. Please note +Currently supports all modern browsers (if you use a build step): IE 9+, Chrome 7+, FireFox 4+, Safari 5+. Please note that the should style is currently not compatible with IE9.

If you want to know if your browser is compatible, run the online test suite. diff --git a/_guides/plugins.md b/_guides/plugins.md index 8be2ae3..30a5d02 100644 --- a/_guides/plugins.md +++ b/_guides/plugins.md @@ -30,7 +30,8 @@ by using the use method of the chai export, which accepts a single function as an argument.

-chai.use(function (_chai, utils) {
+import {use} from 'chai'
+use(function (_chai, utils) {
   // ...
 });

@@ -46,9 +47,8 @@ community. A more appropriate pattern for creating helpers is as follows... For our helper file: test/helpers/model.js

-module.exports = function (chai, utils) {
-  var Assertion = chai.Assertion;
-
+import {Assertion} from 'chai'
+export function chaiModel(chai, utils) {
   // your helpers here
 };

@@ -56,11 +56,10 @@ module.exports = function (chai, utils) { And, for our actual test: test/person.js

-var chai = require('chai')
-  , chaiModel = require('./helpers/model')
-  , expect = chai.expect;
+import {expect, use} from 'chai'
+import {chaiModel} from './helpers/model'

-chai.use(chaiModel);
+use(chaiModel);

For the rest of this document, we will assume this structure... diff --git a/_guides/styles.md b/_guides/styles.md index de9a264..1859753 100644 --- a/_guides/styles.md +++ b/_guides/styles.md @@ -28,8 +28,8 @@ node.js. This assert module, however, provides several additional tests and is browser compatible.

-var assert = require('chai').assert
-  , foo = 'bar'
+import {assert} from 'chai'
+var foo = 'bar'
   , beverages = { tea: [ 'chai', 'matcha', 'oolong' ] };

 assert.typeOf(foo, 'string'); // without optional message
@@ -59,8 +59,8 @@ The BDD style is exposed through `expect` or `should` interfaces. In both
 scenarios, you chain together natural language assertions.

 ```js
-var expect = require('chai').expect
-  , foo = 'bar'
+import {expect} from 'chai'
+var foo = 'bar'
   , beverages = { tea: [ 'chai', 'matcha', 'oolong' ] };

 expect(foo).to.be.a('string');
@@ -94,8 +94,9 @@ property to start your chain. This style has some issues when used with Internet
 Explorer, so be aware of browser compatibility.

 ```js
-var should = require('chai').should() //actually call the function
-  , foo = 'bar'
+import {should} from 'chai'
+should()
+var foo = 'bar'
   , beverages = { tea: [ 'chai', 'matcha', 'oolong' ] };

 foo.should.be.a('string');
@@ -106,14 +107,13 @@ beverages.should.have.property('tea').with.lengthOf(3);

 ### Differences

-First of all, notice that the `expect` require is just a reference to the
-`expect` function, whereas with the `should` require, the function is
-being executed.
+First of all, notice that `assert`and `expect` are references to the
+respective functions, whereas with the `should`, the function is
+being executed to set up the leading `should` in your assertion chains.

 ```js
-var chai = require('chai')
-  , expect = chai.expect
-  , should = chai.should();
+import {expect, should} from 'chai'
+should()

The expect interface provides a function as a starting point for chaining @@ -143,7 +143,8 @@ with a should chain starter. As such, the appropriate few assertions for this scenario are as follows:

-var should = require('chai').should();
+import {should} from 'chai'
+should()
 db.get(1234, function (err, doc) {
   should.not.exist(err);
   should.exist(doc);
@@ -161,22 +162,6 @@ quick helpers to keep you out of trouble when using `should`.
 - `should.Throw`
 - `should.not.Throw`

-### Using Should in ES2015
-
-It isn't possible to chain a function call from an ES2015 `import`
-statement – it has to go on its own line, which looks a little
-verbose:
-
-```js
-import chai from 'chai';
-chai.should();
-```
-
-For a cleaner look, you can do this instead:
-
-```js
-import 'chai/register-should';
-```

 ## Configuration

@@ -190,7 +175,8 @@ Assertion error message. Default of `false` suppresses stack trace in the error
 message.

 ```javascript
-chai.config.includeStack = true; // turn on stack trace
+import {config} from 'chai'
+config.includeStack = true; // turn on stack trace

config.showDiff

@@ -203,7 +189,8 @@ should be included in the thrown AssertionErrors. false will always be false true will be true when the assertion has requested a diff be shown.

-chai.config.showDiff = false; // turn off reporter diff display
+import {config} from 'chai'
+config.showDiff = false; // turn off reporter diff display

config.truncateThreshold

@@ -217,5 +204,6 @@ in assertion errors. If this threshold is exceeded, the value is truncated. Set it to zero if you want to disable truncating altogether.

-chai.config.truncateThreshold = 0; // disable truncating
+import {config} from 'chai'
+config.truncateThreshold = 0; // disable truncating

diff --git a/index.html b/index.html index 96895dc..5ad5541 100644 --- a/index.html +++ b/index.html @@ -18,7 +18,8 @@ includeBanner: true

Should

{% highlight js %} -chai.should(); +import {should} from 'chai'; +should(); foo.should.be.a('string'); foo.should.equal('bar'); @@ -38,7 +39,7 @@ tea.should.have.property('flavors')

Expect

{% highlight js %} -var expect = chai.expect; +import {expect} from 'chai'; expect(foo).to.be.a('string'); expect(foo).to.equal('bar'); @@ -58,7 +59,7 @@ expect(tea).to.have.property('flavors')

Assert

{% highlight js %} -var assert = chai.assert; +import {assert} from 'chai'; assert.typeOf(foo, 'string'); assert.equal(foo, 'bar'); ``````
  • © Githubissues.
  • Githubissues is a development platform for aggregating issues.