codeceptjs 4.0.0-rc.2 → 4.0.0-rc.20

package/docs/internal-api.md

@@ -0,0 +1,265 @@
+---
+permalink: /internal-api
+title: Internal API
+---
+
+## Concepts
+
+In this guide we will overview the internal API of CodeceptJS.
+This knowledge is required for customization, writing plugins, etc.
+
+CodeceptJS exposes its internal API as named exports of the `codeceptjs` package. Import only what you need:
+
+```js
+import { recorder, event, output, container, config } from 'codeceptjs'
+```
+
+> Older code may have relied on a global `codeceptjs` object (`const { recorder } = codeceptjs`). That global only exists under `noGlobals: false` (the deprecated 3.x default) — prefer named imports.
+
+These internal objects are available:
+
+* [`codecept`](https://github.com/Codeception/CodeceptJS/blob/master/lib/codecept.js): test runner class
+* [`config`](https://github.com/Codeception/CodeceptJS/blob/master/lib/config.js): current codecept config
+* [`event`](https://github.com/Codeception/CodeceptJS/blob/master/lib/event.js): event listener
+* [`recorder`](https://github.com/Codeception/CodeceptJS/blob/master/lib/recorder.js): global promise chain
+* [`output`](https://github.com/Codeception/CodeceptJS/blob/master/lib/output.js): internal printer
+* [`container`](https://github.com/Codeception/CodeceptJS/blob/master/lib/container.js): dependency injection container for tests, includes current helpers and support objects
+* [`helper`](https://github.com/Codeception/CodeceptJS/blob/master/lib/helper.js): basic helper class
+* [`actor`](https://github.com/Codeception/CodeceptJS/blob/master/lib/actor.js): basic actor (I) class
+
+[API reference](https://github.com/Codeception/CodeceptJS/tree/master/docs/api) is available on GitHub.
+Also please check the source code of corresponding modules.
+
+### Container
+
+CodeceptJS has a dependency injection container with helpers and support objects.
+They can be retrieved from the container:
+
+```js
+import { container } from 'codeceptjs';
+
+// get object with all helpers
+const helpers = container.helpers();
+
+// get helper by name
+const { WebDriver } = container.helpers();
+
+// get support objects
+const supportObjects = container.support();
+
+// get support object by name
+const { UserPage } = container.support();
+
+// get all registered plugins
+const plugins = container.plugins();
+```
+
+New objects can also be added to container in runtime:
+
+```js
+import { container } from 'codeceptjs';
+import UserPage from './pages/user.js';
+
+container.append({
+  helpers: { // add helper
+    MyHelper: new MyHelper({ config1: 'val1' });
+  },
+  support: { // add page object
+    UserPage,
+  }
+})
+```
+
+> Use this trick to define custom objects inside `boostrap` script
+
+The container also contains the current Mocha instance:
+
+```js
+const mocha = container.mocha();
+```
+
+### Event Listeners
+
+CodeceptJS provides a module with an [event dispatcher and set of predefined events](https://github.com/Codeception/CodeceptJS/blob/master/lib/event.js).
+
+It can be required from codeceptjs package if it is installed locally.
+
+```js
+import { event } from 'codeceptjs';
+
+export default function() {
+
+  event.dispatcher.on(event.test.before, function (test) {
+
+    console.log('--- I am before test --');
+
+  });
+}
+```
+
+Available events:
+
+* `event.test.before(test)` - *async* when `Before` hooks from helpers and from test is executed
+* `event.test.after(test)` - *async* after each test
+* `event.test.started(test)` - *sync* at the very beginning of a test.
+* `event.test.passed(test)` - *sync* when test passed
+* `event.test.failed(test, error)` - *sync* when test failed
+* `event.test.finished(test)` - *sync* when test finished
+* `event.suite.before(suite)` - *async* before a suite
+* `event.suite.after(suite)` - *async* after a suite
+* `event.step.before(step)` - *async* when the step is scheduled for execution
+* `event.step.after(step)`- *async* after a step
+* `event.step.started(step)` - *sync* when step starts.
+* `event.step.passed(step)` - *sync* when step passed.
+* `event.step.failed(step, err)` - *sync* when step failed.
+* `event.step.finished(step)` - *sync* when step finishes.
+* `event.step.comment(step)` - *sync* fired for comments like `I.say`.
+* `event.all.before` - before running tests
+* `event.all.after` - after running tests
+* `event.all.result` - when results are printed
+* `event.workers.before` - before spawning workers in parallel run
+* `event.workers.after` - after workers finished in parallel run
+* `event.workers.result` - test results after workers finished in parallel run
+
+
+> *sync* - means that event is fired in the moment of the action happening.
+ *async* - means that event is fired when an action is scheduled. Use `recorder` to schedule your actions.
+
+For further reference look for [currently available listeners](https://github.com/Codeception/CodeceptJS/tree/master/lib/listener) using the event system.
+
+
+### Recorder
+
+To inject asynchronous functions in a test or before/after a test you can subscribe to corresponding event and register a function inside a recorder object. [Recorder](https://github.com/Codeception/CodeceptJS/blob/master/lib/recorder.js) represents a global promises chain.
+
+Provide a function in the first parameter, a function must be async or must return a promise:
+
+```js
+import { event, recorder } from 'codeceptjs';
+import request from 'request';
+
+export default function() {
+
+  event.dispatcher.on(event.test.before, function (test) {
+
+    recorder.add('create fixture data via API', function() {
+      return new Promise((doneFn, errFn) => {
+        request({
+          baseUrl: 'http://api.site.com/',
+          method: 'POST',
+          url: '/users',
+          json: { name: 'john', email: 'john@john.com' }
+        }), (err, httpResponse, body) => {
+          if (err) return errFn(err);
+          doneFn();
+        }
+      });
+    }
+  });
+}
+```
+
+### Config
+
+CodeceptJS config can be accessed from `import { config } from 'codeceptjs'` then `config.get()`:
+
+```js
+import { config } from 'codeceptjs';
+
+// config object has access to all values of the current config file
+
+if (config.get().myKey == 'value') {
+  // run something
+}
+```
+
+
+### Output
+
+Output module provides four verbosity levels. Depending on the mode you can have different information printed using corresponding functions.
+
+* `default`: prints basic information using `output.print`
+* `steps`: toggled by `--steps` option, prints step execution
+* `debug`: toggled by `--debug` option, prints steps, and debug information with `output.debug`
+* `verbose`: toggled by `--verbose` prints debug information and internal logs with `output.log`
+
+It is recommended to avoid `console.log` and use output.* methods for printing.
+
+```js
+import { output } from 'codeceptjs';
+
+output.print('This is basic information');
+output.debug('This is debug information');
+output.log('This is verbose logging information');
+```
+
+#### Test Object
+
+The test events are providing a test object with following properties:
+
+* `title` title of the test
+* `body` test function as a string
+* `opts` additional test options like retries, and others
+* `pending` true if test is scheduled for execution and false if a test has finished
+* `tags` array of tags for this test
+* `artifacts` list of files attached to this test. Screenshots, videos and other files can be saved here and shared accross different reporters
+* `file` path to a file with a test
+* `steps` array of executed steps (available only in `test.passed`, `test.failed`, `test.finished` event)
+* `skipInfo` additional test options when test skipped 
+* * `message` string with reason for skip
+* * `description` string with test body
+and others
+
+#### Step Object
+
+Step events provide step objects with following fields:
+
+* `name` name of a step, like 'see', 'click', and others
+* `actor` current actor, in most cases it is `I`
+* `helper` current helper instance used to execute this step
+* `helperMethod` corresponding helper method, in most cases is the same as `name`
+* `status` status of a step (passed or failed)
+* `prefix` if a step is executed inside `within` block contain within text, like: 'Within .js-signup-form'.
+* `args` passed arguments
+
+Whenever you execute tests with `--verbose` option you will see registered events and promises executed by a recorder.
+
+## Custom Runner
+
+You can run CodeceptJS tests from your script.
+
+```js
+import { codecept as Codecept } from 'codeceptjs';
+
+// define main config
+const config = { 
+  helpers: { 
+    WebDriver: { 
+      browser: 'chrome', 
+      url: 'http://localhost' 
+    }
+  }
+};
+
+const opts = { steps: true };
+
+// run CodeceptJS inside async function
+(async () => {
+  const codecept = new Codecept(config, options);
+  codecept.init(__dirname);
+
+  try {
+    await codecept.bootstrap();
+    codecept.loadTests('**_test.js');
+    // run tests
+    await codecept.run(test);
+  } catch (err) {
+    printError(err);
+    process.exitCode = 1;
+  } finally {
+    await codecept.teardown();
+  }    
+})();
+```
+
+> Also, you can run tests inside workers in a custom scripts. Please refer to the [parallel execution](/parallel) guide for more details.

package/docs/internal-test-server.md

@@ -0,0 +1,89 @@
+# Internal API Test Server
+
+This directory contains the internal API test server implementation that replaces the third-party `json-server` dependency.
+
+## Files
+
+- `lib/test-server.js` - Main TestServer class implementation
+- `bin/test-server.js` - CLI script to run the server standalone
+
+## Usage
+
+### As npm script:
+
+```bash
+npm run test-server
+```
+
+### Directly:
+
+```bash
+node bin/test-server.js [options] [db-file]
+```
+
+### Options:
+
+- `-p, --port <port>` - Port to listen on (default: 8010)
+- `--host <host>` - Host to bind to (default: 0.0.0.0)
+- `db-file` - Path to JSON database file (default: test/data/rest/db.json)
+
+## Features
+
+- **Full REST API compatibility** with json-server
+- **Automatic file watching** - Reloads data when db.json file changes
+- **CORS support** - Allows cross-origin requests for testing
+- **Custom headers support** - Handles special headers like X-Test
+- **File upload endpoints** - Basic file upload simulation
+- **Express.js based** - Uses familiar Express.js framework
+
+## API Endpoints
+
+The server provides the same API endpoints as json-server:
+
+### Users
+
+- `GET /user` - Get user data
+- `POST /user` - Create/update user
+- `PATCH /user` - Partially update user
+- `PUT /user` - Replace user
+
+### Posts
+
+- `GET /posts` - Get all posts
+- `GET /posts/:id` - Get specific post
+- `POST /posts` - Create new post
+- `PUT /posts/:id` - Replace specific post
+- `PATCH /posts/:id` - Partially update specific post
+- `DELETE /posts/:id` - Delete specific post
+
+### Comments
+
+- `GET /comments` - Get all comments
+- `POST /comments` - Create new comment
+- `DELETE /comments/:id` - Delete specific comment
+
+### Utility
+
+- `GET /headers` - Return request headers (for testing)
+- `POST /headers` - Return request headers (for testing)
+- `POST /upload` - File upload simulation
+- `POST /_reload` - Manually reload database file
+
+## Migration from json-server
+
+This server is designed as a drop-in replacement for json-server. The key differences:
+
+1. **No CLI options** - Configuration is done through constructor options or CLI args
+2. **Automatic file watching** - No need for `--watch` flag
+3. **Built-in middleware** - Headers and CORS are handled automatically
+4. **Simpler file upload** - Basic implementation without full multipart support
+
+## Testing
+
+The server is used by the following test suites:
+
+- `test/rest/REST_test.js` - REST helper tests
+- `test/rest/ApiDataFactory_test.js` - API data factory tests
+- `test/helper/JSONResponse_test.js` - JSON response helper tests
+
+All tests pass with the internal server, proving full compatibility.