Dynamically select emulator ports from machine instead of static port…

…s specified by user or defaults (#117)

.changeset/rare-starfishes-mate.md

@@ -0,0 +1,5 @@
+---
+"flow-js-testing": minor
+---
+
+Dynamically select ports for emulator instead of supplying admin port statically through emulator.start arguments, deprecate use of this argument

README.md

@@ -6,14 +6,14 @@
   <p align="center">
     <i>Test your Flow applications written in Cadence with ease</i>
     <br />
-    <a href="/docs/examples/basic.md"><strong>Quick Intro»</strong></a>
+    <a href="https://docs.onflow.org/flow-js-testing/"><strong>Read the docs</strong></a>
     <br />
     <br />
     <a href="https://github.com/onflow/flow-js-testing/issues">Report Bug</a>
     ·
     <a href="https://github.com/onflow/flow-js-testing/blob/master/CONTRIBUTING.md">Contribute</a>
     ·
-    <a href="/docs/install.md">Installation</a>
+    <a href="https://docs.onflow.org/flow-js-testing/install/">Installation</a>
   </p>
 </div>
 
@@ -34,15 +34,9 @@ Most of the methods will not work, unless you have Flow Emulator running in the
 You can install it alongside Flow CLI. Please refer to [Install Flow CLI](https://docs.onflow.org/flow-cli/install)
 for instructions.
 
-If you have it already installed, run the `flow init` in your terminal to create `flow.json` config file.
-Then start the emulator with `flow emulator -v`.
+If you have it already installed, run the `flow init` in your terminal to create `flow.json` config file in the root directory of your tests.
 
-## Documentation
-
-- [Installation](/docs/install.md)
-- [API](/docs/api.md)
-- Extra Examples
-  - [Metadata](/docs/examples/metadata.md)
+In order to use the emulator within your tests, please refer to the [documentation](https://docs.onflow.org/flow-js-testing/emulator/).
 
 ## Playground Integration
 

TRANSITIONS.md

@@ -0,0 +1,12 @@
+# Transitions
+
+## 0001 Deprecate `emulator.start()` port argument
+
+- **Date:** Jun 28 2022
+- **Type:** Depreaction of `port` argument for `emulator.start()`
+
+`emulator.start` was previously called with the arguments: `emulator.start(port, options = {})`. The `port` argument has now been removed and manual specification of the ports is no longer recommended.
+
+However, the `adminPort`, `restPort`, and `grpcPort` of the emulator may be overriden as fields in `options` (i.e. `options.restPort = 1234`) if absolutely necessary - however their use is not advisable and may cause unintended consequences.
+
+Instead, it is recommended omit supplying a static a port and allow flow-js-testing to automatically determine available ports to supply the emululator. Flow-js-testing will automatically configure @onflow/fcl to use these ports for all of its functionality.

dev-test/deploy.test.js

@@ -19,9 +19,8 @@ describe("interactions - sendTransaction", () => {
   // Instantiate emulator and path to Cadence files
   beforeEach(async () => {
     const basePath = path.resolve(__dirname, "./cadence");
-    const port = 8080;
     await init(basePath);
-    return emulator.start(port);
+    return emulator.start();
   });
 
   // Stop emulator, so it could be restarted

dev-test/imports.test.js

@@ -16,7 +16,7 @@ describe("import resolver", () => {
     const basePath = path.resolve(__dirname, "./cadence");
     const port = 8081;
     await init(basePath, { port });
-    return emulator.start(port, false);
+    return emulator.start();
   });
 
   // Stop emulator, so it could be restarted

dev-test/interaction.test.js

@@ -17,9 +17,8 @@ describe("interactions - sendTransaction", () => {
   // Instantiate emulator and path to Cadence files
   beforeEach(async () => {
     const basePath = path.resolve(__dirname, "./cadence");
-    const port = 8082;
-    await init(basePath, { port });
-    return emulator.start(port);
+    await init(basePath);
+    return emulator.start();
   });
 
   // Stop emulator, so it could be restarted
@@ -132,9 +131,8 @@ describe("interactions - executeScript", () => {
   // Instantiate emulator and path to Cadence files
   beforeEach(async () => {
     const basePath = path.resolve(__dirname, "./cadence");
-    const port = 8080;
-    await init(basePath, { port });
-    return emulator.start(port, false);
+    await init(basePath);
+    return emulator.start();
   });
 
   // Stop emulator, so it could be restarted
@@ -167,7 +165,7 @@ describe("interactions - executeScript", () => {
   });
 
   test("executeScript - shall pass with short notation", async () => {
-    const [result,err] = await shallResolve(executeScript("log-message"));
+    const [result, err] = await shallResolve(executeScript("log-message"));
     expect(err).toBe(null);
     expect(result).toBe(42);
   });
@@ -191,8 +189,8 @@ describe("interactions - executeScript", () => {
       }
     `;
       const args = [[]];
-      return  executeScript({ code, args });
-    })
+      return executeScript({ code, args });
+    });
     expect(err).toBe(null);
     expect(result.length).toBe(0);
   });

dev-test/metadata.test.js

@@ -6,9 +6,8 @@ jest.setTimeout(10000);
 describe("metadata examples", () => {
   beforeEach(async () => {
     const basePath = path.resolve("./cadence");
-    const port = 8083;
     await init(basePath);
-    return emulator.start(port);
+    return emulator.start();
   });
 
   afterEach(async () => {

dev-test/usage.test.js

@@ -23,9 +23,8 @@ describe("Basic Usage test", () => {
   // Instantiate emulator and path to Cadence files
   beforeEach(async () => {
     const basePath = path.resolve(__dirname, "./cadence");
-    const port = 8084;
     await init(basePath);
-    return emulator.start(port);
+    return emulator.start();
   });
 
   // Stop emulator, so it could be restarted
@@ -80,9 +79,8 @@ describe("Basic Usage test", () => {
 describe("jest methods", () => {
   beforeEach(async () => {
     const basePath = path.resolve(__dirname, "./cadence");
-    const port = 8082;
     await init(basePath);
-    return emulator.start(port);
+    return emulator.start();
   });
 
   // Stop emulator, so it could be restarted
@@ -146,10 +144,9 @@ describe("jest methods", () => {
 describe("Path arguments", () => {
   beforeEach(async () => {
     const basePath = path.resolve(__dirname, "./cadence");
-    const port = 8082;
     await init(basePath);
 
-    return emulator.start(port, true);
+    return emulator.start();
   });
 
   // Stop emulator, so it could be restarted

dev-test/utilities.test.js

@@ -24,9 +24,8 @@ describe("block height offset", () => {
   // Instantiate emulator and path to Cadence files
   beforeEach(async () => {
     const base = path.resolve(__dirname, "../cadence");
-    const port = 8085;
-    await init({ base },);
-    return emulator.start(port);
+    await init({ base });
+    return emulator.start();
   });
 
   // Stop emulator, so it could be restarted
@@ -59,7 +58,6 @@ describe("block height offset", () => {
     const [offSet] = await getBlockOffset({ addressMap });
 
     expect(offSet).toBe(0);
-
   });
 
   it("should update offset with utility method", async () => {
@@ -87,9 +85,8 @@ describe("block height offset utilities", () => {
   // Instantiate emulator and path to Cadence files
   beforeEach(async () => {
     const base = path.resolve(__dirname, "../cadence");
-    const port = 8080;
-    await init({ base }, { port });
-    return emulator.start(port);
+    await init({ base });
+    return emulator.start();
   });
 
   // Stop emulator, so it could be restarted
@@ -118,9 +115,8 @@ describe("dev tests", () => {
   // Instantiate emulator and path to Cadence files
   beforeEach(async () => {
     const base = path.resolve(__dirname, "../cadence");
-    const port = 8080;
-    await init({ base }, { port });
-    return emulator.start(port, false);
+    await init({ base });
+    return emulator.start();
   });
 
   // Stop emulator, so it could be restarted

docs/README.md

@@ -1,4 +1,4 @@
 # Flow Javascript Testing Framework Documentation
 
 This directory contains the source files for the Flow Javascript Testing Framework documentation.
-Read the full version on the [Flow documentation website](https://docs.onflow.org/flow-cli).
+Read the full version on the [Flow documentation website](https://docs.onflow.org/flow-js-testing/).