Merge pull request #206 from chaijs/koddsson/add-esm-guide

Add guide on using Chai with ESM and plugins

Author: Kristján Oddsson

_guides/index.md

@@ -17,6 +17,7 @@ assertion styles.
 
 - [Install Chai]({{site.github.url}}/guide/installation/) in node, the browser, and other environments.
 - [Learn about styles]({{site.github.url}}/guide/styles/) that you can use to define assertions.
+- [Importing Chai, and using plugins]({{site.github.url}}/guide/using-chai-with-esm-and-plugins/) to learn how to use Chai with ESM and plugins.
 
 ## Making Plugins
 
@@ -26,5 +27,76 @@ than what is included, limited only by what you want to achieve. The Plugin API
 is also intended as a way to simplify testing by providing users a way to
 encapsulate common assertions for repeat use.
 
+### Exposing Globals in Plugins
+
+When creating a Chai plugin, it's possible to expose globals that can be used across multiple files. Here's how to do it sustainably:
+
+#### Good Practice
+
+Prefer exporting any global in the module record so it can be imported directly instead of adding it as a property in the chai object:
+
+```javascript
+// An example of a good plugin:
+
+export const myGlobal = {...};
+
+export default function myPlugin(chai, utils) {
+}
+```
+
+#### Potential Issues
+
+Avoid exposing globals only through `chai.use()` without making them available for import, as this can lead to issues when trying to use the global across multiple files:
+
+```javascript
+// An example of a plugin which may have issues:
+
+const myGlobal = {...};
+
+export default function myPlugin(chai, utils) {
+  chai.myGlobal = myGlobal;
+}
+```
+
+```javascript
+// Another example of a plugin which may have issues:
+
+export default function myPlugin(chai, utils) {
+  chai.myGlobal = {...};
+}
+```
+
+### Guard against multiple calls to `use(..)`
+
+In certain situations the `use(..)` function  could be called multiple times with your plugin. For a lot of plugins this won't be a issue but it's considered best practise to check if the plugin has been applied already.
+
+Here's a contrived example of how you might implement a check in your plugin but the actual implementation is left up to the plugin author.
+
+```js
+import * as chai from 'chai';
+
+let overwritten = false;
+
+function somePlugin(base) {
+  if (!overwritten) {
+    base.util.overwriteMethod(base.Assertion.prototype, "equal", function (_super) {
+      return function(...args) {
+        console.log("Called!"); // log something out
+
+        return _super.call(this, ...args);
+      };
+    });
+    overwritten = true;
+  }
+}
+
+chai.use(somePlugin);
+chai.use(somePlugin);
+
+chai.expect(123).to.equal(123); // Logs `Called!` only once
+```
+
+By following these guidelines, you can create Chai plugins that are easy to use and maintain.
+
 - [Core Plugin Concepts]({{site.github.url}}/guide/plugins/) covers the basics of using the Chai Plugin API.
 - [Building a Helper]({{site.github.url}}/guide/helpers/) is a walkthrough for writing your first plugin.

_guides/using-chai-with-esm-and-plugins.md

@@ -0,0 +1,59 @@
+---
+  title: Using Chai with ESM and Plugins
+  layout: guide
+  bodyClass: guide
+  weight: 0
+  order: 20
+  headings:
+    - Importing Chai
+    - Using Plugins
+    - Exposing Globals in Plugins
+---
+
+# Using Chai with ESM and Plugins
+
+This guide provides an overview of how to use Chai with ECMAScript modules (ESM) and plugins, including examples using the `chai-http` plugin.
+
+## Importing Chai
+
+To use Chai with ESM, you can import Chai in your test files using the `import` statement. Here's how you can import the `expect` interface:
+
+```javascript
+import { expect } from 'chai';
+```
+
+## Using Plugins
+
+Chai plugins can extend Chai's capabilities. To use a plugin, you first need to install it, then use the `use` method to load it. Here's how to use the `chai-http` plugin as an example:
+
+```javascript
+import chai from 'chai';
+import { request }, chaiHttp from 'chai-http';
+
+chai.use(chaiHttp);
+
+// Now you can use `chai-http` using the `request` function.
+```
+
+### chai-http Example
+
+Here's an example of using `chai-http` to test an HTTP GET request:
+
+```javascript
+import chai, { expect } from 'chai';
+import { request }, chaiHttp from 'chai-http';
+
+chai.use(chaiHttp);
+
+describe('GET /user', () => {
+  it('should return the user', done => {
+    request('http://example.com')
+      .get('/user')
+      .end((err, res) => {
+        expect(res).to.have.status(200);
+        expect(res.body).to.be.an('object');
+        done();
+      });
+  });
+});
+```