First valuable commit

Author: NicholasBoll

README.md

@@ -1,2 +1,61 @@
-# cypress-time
+## cypress-time
 Record timings in Cypress
+
+## Why?
+Sometimes you want to record how long a series of tasks/actions take. When developing, you might use browser-based time spans to give you feedback. This Cypress plugin will give you a nice way to do timings right in your test! This library uses the [User Timings API](https://developer.mozilla.org/en-US/docs/Web/API/User_Timing_API), so the time span will show up if you run a performance profile while the test is active (can only be done using `cypress open` which is dev mode).
+
+## Installation
+To install the module:
+```
+npm install cypress-time --save-dev
+```
+
+To get the plugin working with Cypress:
+```js
+// cypress/support/index.js or cypress/support/index.ts
+import 'cypress-time'
+```
+
+## Use
+In your spec files, `cy.time(label)` will start a time span while `cy.timeEnd(label)` will end a time span. `cy.timeEnd` will return a [PerformanceEntry](https://developer.mozilla.org/en-US/docs/Web/API/PerformanceEntry).
+
+```js
+// start the 'test' time span
+cy.time('test')
+
+cy.contains('button', 'Submit').click()
+
+// wait until submit is complete - assume a backend is involved
+cy.get('Loading').should('not.exist')
+
+// ends the 'test' time span, printing the duration
+cy.timeEnd('test')
+```
+
+If you want to do something with the time output, the [PerformanceEntry](https://developer.mozilla.org/en-US/docs/Web/API/PerformanceEntry) is returned. You can save this to a file, send it off to a service, or whatever you'd like. `startTime` and `duration` may be of the most interest.
+
+```js
+cy.time('test')
+
+// do something
+
+cy.timeEnd('test').then(entry => {
+  console.log(entry.startTime) // start in ms elapsed since page loaded
+  console.log(entry.duration) // duration between `time` and `timeEnd`
+})
+```
+
+**Here's a screenshot of what the command log will look like:**
+![Cypress Command Log](./time-span-command-log.png)
+
+**Here's a screenshot of the Performance tools with the 'test' time span:**
+![Performance Tab of Time Span](./time-span-performance.png)
+
+## Typescript support
+This plugin comes with its own type definitions. If you're using Typescript already and your support index file is a Typescript file and your tsconfig.json is configured to include *.ts files in the support directory, nothing more needs to be done. If you don't have your project set up this way, add the following to your tsconfig (ideally in `cypress/tsconfig.json`):
+
+```json
+{
+  "types" ["cypress", "cypress-time"]
+}
+```

cypress.json

@@ -0,0 +1 @@
+{}

cypress/fixtures/example.json

@@ -0,0 +1,5 @@
+{
+  "name": "Using fixtures to represent data",
+  "email": "[email protected]",
+  "body": "Fixtures are a great way to mock data for responses to routes"
+}

cypress/integration/time.spec.js

@@ -0,0 +1,12 @@
+/// <reference types="cypress" />
+/// <reference path="../../index.d.ts" />
+
+describe('time', () => {
+  it('should show timings', () => {
+    cy.time('test')
+    cy.wrap('foo').wait(300)
+    cy.timeEnd('test')
+      .its('duration')
+      .should('be.a', 'number')
+  })
+})

cypress/plugins/index.js

@@ -0,0 +1,21 @@
+/// <reference types="cypress" />
+// ***********************************************************
+// This example plugins/index.js can be used to load plugins
+//
+// You can change the location of this file or turn off loading
+// the plugins file with the 'pluginsFile' configuration option.
+//
+// You can read more here:
+// https://on.cypress.io/plugins-guide
+// ***********************************************************
+
+// This function is called when a project is opened or re-opened (e.g. due to
+// the project's config changing)
+
+/**
+ * @type {Cypress.PluginConfig}
+ */
+module.exports = (on, config) => {
+  // `on` is used to hook into various events Cypress emits
+  // `config` is the resolved Cypress config
+}

cypress/support/index.js

@@ -0,0 +1,2 @@
+// import the time commands
+import '../../index'

index.d.ts

@@ -0,0 +1,20 @@
+/// <reference types="cypress" />
+
+namespace Cypress {
+  interface Chainable<Subject = any> {
+    /**
+     * Starts a time span using the User Timings API. A `cy.time`
+     * should always be followed by a `cy.timeEnd` with the same label.
+     * This command is useful for getting durations for a series of
+     * commands and getting performance profiles out of your application
+     * given some series of commands you want to profile.
+     * @param label Name of the time span you wish to capture
+     */
+    time(label: string): Chainable<null>;
+    /**
+     * Ends a time span using the User Timings API.
+     * @param label Name of the time span you wish to capture
+     */
+    timeEnd(label: string): Chainable<PerformanceEntry>;
+  }
+}

index.js

@@ -0,0 +1,20 @@
+Cypress.Commands.add('time', name => {
+  performance.mark(`${name}_start`);
+  cy.state(name, performance.now());
+  Cypress.log({
+    name: 'time',
+  }).end();
+  return null;
+});
+
+Cypress.Commands.add('timeEnd', name => {
+  performance.mark(`${name}_end`);
+  performance.measure(name, `${name}_start`, `${name}_end`)
+  const data = performance.getEntriesByName(name)[0]
+  console.log(data)
+  Cypress.log({
+    name: 'timeEnd',
+    message: [name, `${data.duration.toFixed(2)}ms`],
+  });
+  return data;
+});