@serenity-js/rest 3.33.1 → 3.34.1

package/lib/screenplay/abilities/CallAnApi.js

@@ -11,12 +11,6 @@ const io_1 = require("../../io");
  * the [actor](https://serenity-js.org/api/core/class/Actor/) to [send](https://serenity-js.org/api/rest/class/Send/)
  * [HTTP requests](https://serenity-js.org/api/rest/class/HTTPRequest/) to HTTP APIs.
  *
- * `CallAnApi` uses [`proxy-from-env`](https://www.npmjs.com/package/proxy-from-env) and an approach
- * described in ["Node.js Axios behind corporate proxies"](https://janmolak.com/node-js-axios-behind-corporate-proxies-8b17a6f31f9d)
- * to automatically detect proxy server configuration based
- * on your [environment variables](https://www.npmjs.com/package/proxy-from-env#environment-variables).
- * You can override this configuration if needed.
- *
  * ## Configuring the ability to call an API
  *
  * The easiest way to configure the ability to `CallAnApi` is to provide the `baseURL` of your HTTP API,
@@ -37,6 +31,12 @@ const io_1 = require("../../io");
  *   )
  * ```
  *
+ * Please note that the following Serenity/JS test runner adapters already provide the ability to `CallAnApi` as part of their default configuration,
+ * so you don't need to configure it yourself:
+ * - [Playwright Test](https://serenity-js.org/handbook/test-runners/playwright-test/)
+ * - [WebdriverIO](https://serenity-js.org/handbook/test-runners/webdriverio/)
+ * - [Protractor](https://serenity-js.org/handbook/test-runners/protractor/)
+ *
  * ### Resolving relative URLs
  *
  * Serenity/JS resolves request URLs using Node.js [WHATWG URL API](https://nodejs.org/api/url.html#new-urlinput-base).
@@ -95,12 +95,34 @@ const io_1 = require("../../io");
  *   )
  * ```
  *
- * ### Working with proxy servers
+ * ## Working with proxy servers
+ *
+ * `CallAnApi` uses an approach described in ["Node.js Axios behind corporate proxies"](https://janmolak.com/node-js-axios-behind-corporate-proxies-8b17a6f31f9d)
+ * to automatically detect proxy server configuration based on your environment variables.
+ *
+ * You can override this default proxy detection mechanism by providing your own proxy configuration object.
+ *
+ * ### Automatic proxy support
  *
- * `CallAnApi` uses [`proxy-from-env`](https://www.npmjs.com/package/proxy-from-env) to automatically
- * detect proxy server configuration based on your [environment variables](https://www.npmjs.com/package/proxy-from-env#environment-variables).
+ * When the URL you're sending the request to uses the HTTP protocol, Serenity/JS will automatically detect your proxy configuration based on the following environment variables:
+ * - `npm_config_http_proxy`
+ * - `http_proxy` and `HTTP_PROXY`
+ * - `npm_config_proxy`
+ * - `all_proxy`
  *
- * This default behaviour can be overridden by providing explicit proxy configuration:
+ * Similarly, when the request target URL uses the HTTPS protocol, the following environment variables are used instead:
+ * - `npm_config_https_proxy`
+ * - `https_proxy` and `HTTPS_PROXY`
+ * - `npm_config_proxy`
+ * - `all_proxy`
+ *
+ * Proxy configuration is ignored for both HTTP and HTTPS target URLs matching the proxy bypass rules defined in the following environment variables:
+ * - `npm_config_no_proxy`
+ * - `no_proxy` and `NO_PROXY`
+ *
+ * ### Custom proxy configuration
+ *
+ * To override the automatic proxy detection based on the environment variables, provide a proxy configuration object:
  *
  * ```ts
  * import { actorCalled } from '@serenity-js/core'
@@ -115,10 +137,11 @@ const io_1 = require("../../io");
  *         protocol: 'http',
  *         host: 'proxy.example.org',
  *         port: 9000,
- *         auth: {                          // `auth` is optional
+ *         auth: {                          // optional
  *           username: 'proxy-username',
  *           password: 'proxy-password',
- *         }
+ *         },
+ *         bypass: 'status.example.org, internal.example.org'   // optional
  *       }
  *       // ... other configuration options
  *     })
@@ -129,10 +152,31 @@ const io_1 = require("../../io");
  *   )
  * ```
  *
- * Please note that Serenity/JS uses [proxy-agents](https://github.com/TooTallNate/proxy-agents)
+ * Note that Serenity/JS uses [proxy-agents](https://github.com/TooTallNate/proxy-agents)
  * and the approach described in ["Node.js Axios behind corporate proxies"](https://janmolak.com/node-js-axios-behind-corporate-proxies-8b17a6f31f9d)
  * to work around [limited proxy support capabilities](https://github.com/axios/axios/issues?q=is%3Aissue+is%3Aopen+proxy) in Axios itself.
  *
+ * ### Bypassing proxy configuration
+ *
+ * To bypass the proxy configuration for specific hostnames and IP addresses, you can either:
+ * - provide the `bypass` property in the proxy configuration object, or
+ * - use the `no_proxy` environment variable.
+ *
+ * The value of the `bypass` property or the `no_proxy` environment variable should be a comma-separated list of hostnames and IP addresses
+ * that should not be routed through the proxy server, for example: `.com, .serenity-js.org, .domain.com`.
+ *
+ * Note that setting the `bypass` property to `example.org` makes the requests to following URLs bypass the proxy server:
+ * - `api.example.org`
+ * - `sub.sub.example.org`
+ * - `example.org`
+ * - `my-example.org`
+ *
+ * :::info
+ * Serenity/JS doesn't currently support `bypass` rules expressed using CIDR notation, like `192.168.17.0/24`.
+ * Instead, it uses a simple comma-separated list of hostnames and IP addresses.
+ * If you need support for CIDR notation, please [raise an issue](https://github.com/serenity-js/serenity-js/issues).
+ * :::
+ *
  * ### Using Axios instance with proxy support
  *
  * To have full control over the Axios instance used by the ability to `CallAnApi`, you can create it yourself
@@ -147,7 +191,7 @@ const io_1 = require("../../io");
  *
  * import axiosRetry from 'axios-retry'
  *
- * const instance = createAxios({ baseURL 'https://api.example.org/' })
+ * const instance = createAxios({ baseURL: 'https://api.example.org/' })
  * axiosRetry(instance, { retries: 3 })
  *
  * await actorCalled('Apisitt')
@@ -174,7 +218,7 @@ const io_1 = require("../../io");
  * import { axiosCreate } from '@serenity-js/rest'
  * import axiosRetry from 'axios-retry'
  *
- * const instance = axiosCreate({ baseURL 'https://api.example.org/' })
+ * const instance = axiosCreate({ baseURL: 'https://api.example.org/' })
  * axiosRetry(instance, { retries: 3 })
  *
  * await actorCalled('Apisitt')
@@ -471,21 +515,23 @@ function proxyConfigFrom(defaults) {
         return undefined;
     }
     const proxyUrl = defaults.httpAgent.getProxyForUrl(defaults.baseURL);
-    if (!proxyUrl) {
+    try {
+        const url = new node_url_1.URL(proxyUrl);
+        return {
+            protocol: url.protocol?.replace(/:$/, ''),
+            host: url.hostname,
+            port: url.port ? Number(url.port) : undefined,
+            auth: url.username
+                ? {
+                    username: url.username || undefined,
+                    password: url.password || undefined,
+                }
+                : undefined,
+        };
+    }
+    catch {
         return undefined;
     }
-    const url = new node_url_1.URL(proxyUrl);
-    return {
-        protocol: url.protocol?.replace(/:$/, ''),
-        host: url.hostname,
-        port: url.port ? Number(url.port) : undefined,
-        auth: url.username
-            ? {
-                username: url.username || undefined,
-                password: url.password || undefined,
-            }
-            : undefined,
-    };
 }
 function isUndefined(value) {
     return value === undefined;

package/lib/screenplay/abilities/CallAnApi.js.map

@@ -1 +1 @@
-{"version":3,"file":"CallAnApi.js","sourceRoot":"","sources":["../../../src/screenplay/abilities/CallAnApi.ts"],"names":[],"mappings":";;;AAAA,uCAA+B;AAE/B,4CAM2B;AAC3B,2CAAmC;AASnC,oDAAkD;AAGlD,iCAAuC;AAEvC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqTG;AACH,MAAa,SAAU,SAAQ,cAAO;IA+CL;IA7CrB,YAAY,CAAgB;IAEpC;;;;;;OAMG;IACH,MAAM,CAAC,EAAE,CAAC,OAAqB;QAC3B,OAAO,SAAS,CAAC,KAAK,CAAC;YACnB,OAAO,EAAE,OAAO,YAAY,cAAG;gBAC3B,CAAC,CAAC,OAAO,CAAC,QAAQ,EAAE;gBACpB,CAAC,CAAC,OAAO;SAChB,CAAC,CAAC;IACP,CAAC;IAED;;;;;;;;;;;;;;;;OAgBG;IACH,MAAM,CAAC,KAAK,CAAC,qBAAiE;QAC1E,OAAO,IAAI,SAAS,CAAC,IAAA,gBAAW,EAAC,qBAAqB,CAAC,CAAC,CAAC;IAC7D,CAAC;IAED;;;;;;OAMG;IACH,YAA6B,aAA4B;QACrD,KAAK,EAAE,CAAC;QADiB,kBAAa,GAAb,aAAa,CAAe;IAEzD,CAAC;IAED;;;;;;;;;OASG;IACH,YAAY,CAAC,EAAyC;QAClD,EAAE,CAAC,IAAI,CAAC,aAAa,CAAC,QAAQ,CAAC,CAAC;IACpC,CAAC;IAED;;;;;;;;;;;;OAYG;IACH,KAAK,CAAC,OAAO,CAAC,MAA0B;QACpC,IAAI,GAAW,CAAC;QAEhB,IAAI,CAAC;YACD,GAAG,GAAG,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC;YAC9B,IAAI,CAAC,YAAY,GAAG,MAAM,IAAI,CAAC,aAAa,CAAC,OAAO,CAAC;gBACjD,GAAG,MAAM;gBACT,GAAG;aACN,CAAC,CAAC;YAEH,OAAO,IAAI,CAAC,YAAY,CAAC;QAC7B,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACb,MAAM,WAAW,GAAG,GAAG,MAAM,CAAC,MAAM,CAAC,WAAW,EAAE,IAAI,GAAG,IAAI,MAAM,CAAC,GAAG,EAAE,CAAC;YAE1E,QAAQ,IAAI,EAAE,CAAC;gBACX,KAAK,mBAAmB,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC;oBACxC,MAAM,IAAI,2BAAoB,CAAC,8BAA8B,WAAW,EAAE,EAAE,KAAK,CAAC,CAAC;gBACvF,KAAK,eAAe,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC;oBACpC,MAAM,IAAI,2BAAoB,CAAC,iCAAiC,WAAW,EAAE,EAAE,KAAK,CAAC,CAAC;gBAC1F,KAAK,KAAK,YAAY,SAAS;oBAC3B,MAAM,IAAI,yBAAkB,CAAC,wDAAwD,EAAE,KAAK,CAAC,CAAC;gBAClG,KAAK,CAAE,KAAoB,CAAC,QAAQ;oBAChC,MAAM,IAAI,2BAAoB,CAAC,4BAA4B,WAAW,EAAE,EAAE,KAAK,CAAC,CAAC;gBACrF;oBACI,IAAI,CAAC,YAAY,GAAG,KAAK,CAAC,QAAQ,CAAC;oBAEnC,OAAO,KAAK,CAAC,QAAQ,CAAC;YAC9B,CAAC;QACL,CAAC;IACL,CAAC;IAED;;;;;;;;OAQG;IACH,UAAU,CAAC,MAA0B;QACjC,MAAM,OAAO,GAAG,IAAI,CAAC,aAAa,CAAC,QAAQ,CAAC,OAAO,IAAI,MAAM,CAAC,OAAO,CAAC;QAEtE,OAAO,OAAO;YACV,CAAC,CAAC,IAAI,cAAG,CAAC,MAAM,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC,QAAQ,EAAE;YACzC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC;IACrB,CAAC;IAED;;;;;;;;OAQG;IACH,eAAe,CAAI,eAA+C;QAC9D,IAAI,CAAC,IAAI,CAAC,YAAY,EAAE,CAAC;YACrB,MAAM,IAAI,iBAAU,CAAC,sEAAsE,CAAC,CAAC;QACjG,CAAC;QAED,OAAO,eAAe,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;IAC9C,CAAC;IAED,MAAM;QACF,MAAM,gBAAgB,GAAe;YACjC,OAAO,EAAE,IAAI,CAAC,aAAa,CAAC,QAAQ,CAAC,OAAO;YAC5C,OAAO,EAAE,IAAI,CAAC,aAAa,CAAC,QAAQ,CAAC,OAAO;YAC5C,OAAO,EAAE,IAAI,CAAC,aAAa,CAAC,QAAQ,CAAC,OAAO;YAC5C,KAAK,EAAI,eAAe,CAAC,IAAI,CAAC,aAAa,CAAC,QAAQ,CAAC;SACxD,CAAC;QAEF,OAAO;YACH,GAAG,KAAK,CAAC,MAAM,EAAE;YACjB,OAAO,EAAE;gBACL,GAAG,iBAAiB,CAChB,CAAC,WAAW,EAAE,aAAa,CAAC,EAC5B,gBAAgB,CACnB;aACJ;SACJ,CAAA;IACL,CAAC;CACJ;AAjKD,8BAiKC;AAED,SAAS,eAAe,CAAC,QAAuB;IAC5C,IAAI,QAAQ,CAAC,KAAK,KAAK,SAAS,EAAE,CAAC;QAC/B,OAAO,SAAS,CAAC;IACrB,CAAC;IAED,IAAI,CAAE,CAAC,QAAQ,CAAC,KAAK,KAAK,KAAK,IAAI,QAAQ,CAAC,SAAS,YAAY,kBAAK,CAAC,EAAE,CAAC;QACtE,OAAO,SAAS,CAAC;IACrB,CAAC;IAED,MAAM,QAAQ,GAAI,QAAQ,CAAC,SAAiB,CAAC,cAAc,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;IAE9E,IAAI,CAAE,QAAQ,EAAE,CAAC;QACb,OAAO,SAAS,CAAC;IACrB,CAAC;IAED,MAAM,GAAG,GAAG,IAAI,cAAG,CAAC,QAAQ,CAAC,CAAC;IAE9B,OAAO;QACH,QAAQ,EAAE,GAAG,CAAC,QAAQ,EAAE,OAAO,CAAC,IAAI,EAAE,EAAE,CAAC;QACzC,IAAI,EAAM,GAAG,CAAC,QAAQ;QACtB,IAAI,EAAM,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,SAAS;QACjD,IAAI,EAAM,GAAG,CAAC,QAAQ;YAClB,CAAC,CAAC;gBACE,QAAQ,EAAE,GAAG,CAAC,QAAQ,IAAI,SAAS;gBACnC,QAAQ,EAAE,GAAG,CAAC,QAAQ,IAAI,SAAS;aACtC;YACD,CAAC,CAAC,SAAS;KAClB,CAAC;AACN,CAAC;AAED,SAAS,WAAW,CAAC,KAAU;IAC3B,OAAO,KAAK,KAAK,SAAS,CAAC;AAC/B,CAAC;AAED,SAAS,aAAa,CAAC,KAAU;IAC7B,OAAO,IAAA,kBAAQ,EAAC,KAAK,CAAC,IAAI,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC;AAC9D,CAAC;AAED,SAAS,iBAAiB,CAAC,QAAwC,EAAE,KAAU;IAC3E,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACvB,OAAO,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,iBAAiB,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC,CAAC;IAChE,CAAC;IAED,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;QAC9C,OAAO,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,GAAG,EAAE,EAAE;YAC1C,IAAI,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;gBAChD,OAAO,GAAG,CAAC;YACf,CAAC;YAED,OAAO;gBACH,GAAG,GAAG;gBACN,CAAC,GAAG,CAAC,EAAE,iBAAiB,CAAC,QAAQ,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC;aACjD,CAAC;QACN,CAAC,EAAE,EAAE,CAAC,CAAC;IACX,CAAC;IAED,OAAO,KAAK,CAAC;AACjB,CAAC"}
+{"version":3,"file":"CallAnApi.js","sourceRoot":"","sources":["../../../src/screenplay/abilities/CallAnApi.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@serenity-js/rest",
-  "version": "3.33.1",
+  "version": "3.34.1",
   "description": "Serenity/JS Screenplay Pattern library for interacting with REST and other HTTP-based services, supporting comprehensive API testing and blended testing scenarios",
   "author": {
     "name": "Jan Molak",
@@ -51,18 +51,17 @@
     "node": "^18.12 || ^20 || ^22"
   },
   "dependencies": {
-    "@serenity-js/core": "3.33.1",
+    "@serenity-js/core": "3.34.1",
     "agent-base": "7.1.4",
     "axios": "1.11.0",
     "http-proxy-agent": "7.0.2",
     "https-proxy-agent": "7.0.6",
     "lru-cache": "11.1.0",
-    "proxy-from-env": "1.1.0",
-    "tiny-types": "1.23.0"
+    "tiny-types": "1.24.1"
   },
   "devDependencies": {
     "@integration/testing-tools": "3.0.0",
-    "@serenity-js/assertions": "3.33.1",
+    "@serenity-js/assertions": "3.34.1",
     "@types/chai": "4.3.20",
     "@types/mocha": "10.0.10",
     "axios-mock-adapter": "2.1.0",
@@ -70,7 +69,7 @@
     "mocha": "11.7.1",
     "mocha-multi": "1.1.7",
     "ts-node": "10.9.2",
-    "typescript": "5.8.3"
+    "typescript": "5.9.2"
   },
-  "gitHead": "11bbc2bb3f6d4d5fade2b7881b36e5259973901a"
+  "gitHead": "8591e154237ca715a067ff5f58351c418416e75a"
 }

package/src/io/AxiosRequestConfigDefaults.ts

@@ -8,6 +8,7 @@ export type AxiosRequestConfigProxyDefaults = {
         password: string;
     };
     protocol?: string;
+    bypass?: string;
 }
 
 export type AxiosRequestConfigDefaults<Data = any> = Omit<CreateAxiosDefaults<Data>, 'proxy'> & {

package/src/io/EnvironmentVariables.ts

@@ -0,0 +1,39 @@
+export class EnvironmentVariables {
+    constructor(private readonly env: NodeJS.ProcessEnv = process.env) {
+    }
+
+    isSet(name: string): boolean {
+        return this.env[name] !== undefined;
+    }
+
+    get(name: string): string | undefined {
+        return this.env[name];
+    }
+
+    find(name: string): string | undefined {
+        const candidateNames = [
+            name,
+            name.toLocaleUpperCase(),
+            name.toLocaleLowerCase(),
+        ];
+
+        for (const variableName of candidateNames) {
+            if (this.isSet(variableName)) {
+                return this.get(variableName);
+            }
+        }
+
+        return undefined;
+    }
+
+    findFirst(...names: string[]): string | undefined {
+        for (const name of names) {
+            const found = this.find(name);
+            if (found) {
+                return found;
+            }
+        }
+
+        return undefined;
+    }
+}

package/src/io/ProxyAgent.ts

@@ -6,7 +6,6 @@ import { HttpProxyAgent, type HttpProxyAgentOptions } from 'http-proxy-agent';
 import * as https from 'https';
 import { HttpsProxyAgent, type HttpsProxyAgentOptions } from 'https-proxy-agent';
 import { LRUCache } from 'lru-cache';
-import { getProxyForUrl as envGetProxyForUrl } from 'proxy-from-env';
 
 const protocols = [
     ...HttpProxyAgent.protocols,
@@ -34,9 +33,7 @@ export type ProxyAgentOptions =
          */
         httpsAgent?: http.Agent;
         /**
-         * A callback for dynamic provision of proxy for url.
-         * Defaults to standard proxy environment variables,
-         * see https://www.npmjs.com/package/proxy-from-env for details
+         * A callback to dynamically determine the proxy to use for the given URL.
          */
         getProxyForUrl?: GetProxyForUrlCallback;
     };
@@ -74,7 +71,7 @@ export class ProxyAgent extends Agent {
         super(agentOptions);
         this.httpAgent      = agentOptions?.httpAgent       || new http.Agent(agentOptions);
         this.httpsAgent     = agentOptions?.httpsAgent      || new https.Agent(agentOptions as https.AgentOptions);
-        this.getProxyForUrl = agentOptions?.getProxyForUrl  || envGetProxyForUrl;
+        this.getProxyForUrl = agentOptions?.getProxyForUrl;
     }
 
     override async connect(request: http.ClientRequest, options: AgentConnectOpts): Promise<http.Agent> {

package/src/io/ProxyBypass.ts

@@ -0,0 +1,83 @@
+import type { URL } from 'node:url';
+
+import { createUrl } from './createUrl';
+
+export abstract class ProxyBypass {
+    static create(value: string | undefined): ProxyBypass {
+        if (value === undefined || value === '') {
+            return new BypassNone();
+        }
+
+        if (value === '*') {
+            return new BypassAll();
+        }
+
+        return new BypassMatching(value);
+    }
+
+    abstract matches(url: URL): boolean;
+}
+
+class BypassNone extends ProxyBypass {
+    matches(url_: URL): boolean {
+        return false;
+    }
+}
+
+class BypassAll extends ProxyBypass {
+    matches(url_: URL): boolean {
+        return true;
+    }
+}
+
+class BypassHostnamePattern extends ProxyBypass {
+    private static readonly template = /^((?<hostname>[^:]+)(:(?<port>\d+))?)$/;
+    private static defaultPorts = {
+        'ftp:': '21',
+        'gopher:': '70',
+        'http:': '80',
+        'https:': '443',
+        'ws:': '80',
+        'wss:': '443',
+    };
+
+    static create(patternConfig: string) {
+        const { hostname, port } = this.template.exec(patternConfig)?.groups || {};
+
+        return new BypassHostnamePattern(hostname, port);
+    }
+
+    private constructor(private readonly hostname: string, private readonly port: string | undefined) {
+        super();
+    }
+
+    matches(url: URL): boolean {
+        const urlPort = url.port || BypassHostnamePattern.defaultPorts[url.protocol]
+
+        return url.hostname.endsWith(this.hostname)
+            && (this.port ? urlPort === this.port : true);
+    }
+}
+
+class BypassMatching extends ProxyBypass {
+
+    private readonly patterns: BypassHostnamePattern[];
+
+    constructor(value: string) {
+        super();
+
+        this.patterns = value.split(',').map(patternConfig => BypassHostnamePattern.create(patternConfig.trim()));
+    }
+
+    matches(url: URL): boolean {
+        const normalisedUrl = createUrl(url);
+
+        for (const pattern of this.patterns) {
+            if (pattern.matches(normalisedUrl)) {
+                return true;
+            }
+        }
+        return false;
+    }
+}
+

package/src/io/createAxios.ts

@@ -1,8 +1,8 @@
 import { Duration } from '@serenity-js/core';
 import axios, { Axios, type AxiosInstance, type AxiosRequestConfig } from 'axios';
 
-import { axiosProxyOverridesFor } from './axiosProxyOverridesFor';
 import type { AxiosRequestConfigDefaults, AxiosRequestConfigProxyDefaults } from './AxiosRequestConfigDefaults';
+import { axiosProxyOverridesFor } from './proxy';
 
 /**
  * Creates an Axios instance with desired configuration and proxy support.

package/src/io/proxy.ts

@@ -0,0 +1,91 @@
+import type * as http from 'node:http';
+import * as process from 'node:process';
+
+import { ensure, isDefined } from 'tiny-types';
+
+import type { AxiosRequestConfigDefaults, AxiosRequestConfigProxyDefaults } from './AxiosRequestConfigDefaults';
+import { createUrl } from './createUrl';
+import { EnvironmentVariables } from './EnvironmentVariables';
+import { ProxyAgent } from './ProxyAgent';
+import { ProxyBypass } from './ProxyBypass';
+
+/**
+ * @param options
+ */
+export function axiosProxyOverridesFor<Data = any>(options: AxiosRequestConfigDefaults<Data>): {
+    proxy: false, httpAgent: http.Agent, httpsAgent: http.Agent
+} {
+    const agent = new ProxyAgent({
+        httpAgent: options.httpAgent,
+        httpsAgent: options.httpsAgent,
+
+        // if there's a specific proxy override configured, use it
+        // if not - detect proxy automatically based on the env variables
+        getProxyForUrl: options.proxy
+            ? createGetProxyForUrlFromConfig(options.proxy)
+            : createGetProxyForUrlFromEnvironmentVariables(new EnvironmentVariables(process.env)),
+    });
+
+    return {
+        proxy: false,
+        httpAgent: agent,
+        httpsAgent: agent,
+    };
+}
+
+export function createGetProxyForUrlFromConfig(proxyOptions: AxiosRequestConfigProxyDefaults): (url: string) => string | undefined {
+    const proxyBypass = ProxyBypass.create(proxyOptions?.bypass);
+
+    return createGetProxyForUrl(proxyBypass, (url: URL): string => {
+        return createUrl({
+            username: proxyOptions.auth?.username,
+            password: proxyOptions.auth?.password,
+            protocol: proxyOptions.protocol,
+            hostname: ensure('proxy.host', proxyOptions?.host, isDefined()),
+            port: proxyOptions.port ? Number(proxyOptions.port) : undefined,
+        }).toString();
+    });
+}
+
+export function createGetProxyForUrlFromEnvironmentVariables(env: EnvironmentVariables): (url: string) => string | undefined {
+    const proxyBypass = ProxyBypass.create(env.findFirst(
+        'npm_config_no_proxy',
+        'no_proxy',
+    ));
+
+    return createGetProxyForUrl(proxyBypass, (url: URL): string => {
+        const protocolName = url.protocol.replace(/:$/, '');
+        const proxyUrl = env.findFirst(
+            `npm_config_${ protocolName }_proxy`,
+            `${ protocolName }_proxy`,
+            'npm_config_proxy',
+            'all_proxy'
+        );
+
+        return proxyUrl || undefined;
+    });
+}
+
+function createGetProxyForUrl(bypass: ProxyBypass, getProxy: (url: URL) => string): (url: string) => string | undefined {
+    return function getProxyForUrl(urlValue: string): string | undefined {
+        if (! isValidUrl(urlValue)) {
+            return undefined;
+        }
+
+        const url = new URL(urlValue);
+
+        return bypass.matches(url)
+            ? undefined
+            : getProxy(url);
+    };
+}
+
+function isValidUrl(url: string): boolean {
+    try {
+        new URL(url);
+        return true;
+    } catch {
+        return false;
+    }
+}
+

package/src/screenplay/abilities/CallAnApi.ts

@@ -26,12 +26,6 @@ import { createAxios } from '../../io';
  * the [actor](https://serenity-js.org/api/core/class/Actor/) to [send](https://serenity-js.org/api/rest/class/Send/)
  * [HTTP requests](https://serenity-js.org/api/rest/class/HTTPRequest/) to HTTP APIs.
  *
- * `CallAnApi` uses [`proxy-from-env`](https://www.npmjs.com/package/proxy-from-env) and an approach
- * described in ["Node.js Axios behind corporate proxies"](https://janmolak.com/node-js-axios-behind-corporate-proxies-8b17a6f31f9d)
- * to automatically detect proxy server configuration based
- * on your [environment variables](https://www.npmjs.com/package/proxy-from-env#environment-variables).
- * You can override this configuration if needed.
- *
  * ## Configuring the ability to call an API
  *
  * The easiest way to configure the ability to `CallAnApi` is to provide the `baseURL` of your HTTP API,
@@ -52,6 +46,12 @@ import { createAxios } from '../../io';
  *   )
  * ```
  *
+ * Please note that the following Serenity/JS test runner adapters already provide the ability to `CallAnApi` as part of their default configuration,
+ * so you don't need to configure it yourself:
+ * - [Playwright Test](https://serenity-js.org/handbook/test-runners/playwright-test/)
+ * - [WebdriverIO](https://serenity-js.org/handbook/test-runners/webdriverio/)
+ * - [Protractor](https://serenity-js.org/handbook/test-runners/protractor/)
+ *
  * ### Resolving relative URLs
  *
  * Serenity/JS resolves request URLs using Node.js [WHATWG URL API](https://nodejs.org/api/url.html#new-urlinput-base).
@@ -110,12 +110,34 @@ import { createAxios } from '../../io';
  *   )
  * ```
  *
- * ### Working with proxy servers
+ * ## Working with proxy servers
+ *
+ * `CallAnApi` uses an approach described in ["Node.js Axios behind corporate proxies"](https://janmolak.com/node-js-axios-behind-corporate-proxies-8b17a6f31f9d)
+ * to automatically detect proxy server configuration based on your environment variables.
+ *
+ * You can override this default proxy detection mechanism by providing your own proxy configuration object.
+ *
+ * ### Automatic proxy support
  *
- * `CallAnApi` uses [`proxy-from-env`](https://www.npmjs.com/package/proxy-from-env) to automatically
- * detect proxy server configuration based on your [environment variables](https://www.npmjs.com/package/proxy-from-env#environment-variables).
+ * When the URL you're sending the request to uses the HTTP protocol, Serenity/JS will automatically detect your proxy configuration based on the following environment variables:
+ * - `npm_config_http_proxy`
+ * - `http_proxy` and `HTTP_PROXY`
+ * - `npm_config_proxy`
+ * - `all_proxy`
  *
- * This default behaviour can be overridden by providing explicit proxy configuration:
+ * Similarly, when the request target URL uses the HTTPS protocol, the following environment variables are used instead:
+ * - `npm_config_https_proxy`
+ * - `https_proxy` and `HTTPS_PROXY`
+ * - `npm_config_proxy`
+ * - `all_proxy`
+ *
+ * Proxy configuration is ignored for both HTTP and HTTPS target URLs matching the proxy bypass rules defined in the following environment variables:
+ * - `npm_config_no_proxy`
+ * - `no_proxy` and `NO_PROXY`
+ *
+ * ### Custom proxy configuration
+ *
+ * To override the automatic proxy detection based on the environment variables, provide a proxy configuration object:
  *
  * ```ts
  * import { actorCalled } from '@serenity-js/core'
@@ -130,10 +152,11 @@ import { createAxios } from '../../io';
  *         protocol: 'http',
  *         host: 'proxy.example.org',
  *         port: 9000,
- *         auth: {                          // `auth` is optional
+ *         auth: {                          // optional
  *           username: 'proxy-username',
  *           password: 'proxy-password',
- *         }
+ *         },
+ *         bypass: 'status.example.org, internal.example.org'   // optional
  *       }
  *       // ... other configuration options
  *     })
@@ -144,10 +167,31 @@ import { createAxios } from '../../io';
  *   )
  * ```
  *
- * Please note that Serenity/JS uses [proxy-agents](https://github.com/TooTallNate/proxy-agents)
+ * Note that Serenity/JS uses [proxy-agents](https://github.com/TooTallNate/proxy-agents)
  * and the approach described in ["Node.js Axios behind corporate proxies"](https://janmolak.com/node-js-axios-behind-corporate-proxies-8b17a6f31f9d)
  * to work around [limited proxy support capabilities](https://github.com/axios/axios/issues?q=is%3Aissue+is%3Aopen+proxy) in Axios itself.
  *
+ * ### Bypassing proxy configuration
+ *
+ * To bypass the proxy configuration for specific hostnames and IP addresses, you can either:
+ * - provide the `bypass` property in the proxy configuration object, or
+ * - use the `no_proxy` environment variable.
+ *
+ * The value of the `bypass` property or the `no_proxy` environment variable should be a comma-separated list of hostnames and IP addresses
+ * that should not be routed through the proxy server, for example: `.com, .serenity-js.org, .domain.com`.
+ *
+ * Note that setting the `bypass` property to `example.org` makes the requests to following URLs bypass the proxy server:
+ * - `api.example.org`
+ * - `sub.sub.example.org`
+ * - `example.org`
+ * - `my-example.org`
+ *
+ * :::info
+ * Serenity/JS doesn't currently support `bypass` rules expressed using CIDR notation, like `192.168.17.0/24`.
+ * Instead, it uses a simple comma-separated list of hostnames and IP addresses.
+ * If you need support for CIDR notation, please [raise an issue](https://github.com/serenity-js/serenity-js/issues).
+ * :::
+ *
  * ### Using Axios instance with proxy support
  *
  * To have full control over the Axios instance used by the ability to `CallAnApi`, you can create it yourself
@@ -162,7 +206,7 @@ import { createAxios } from '../../io';
  *
  * import axiosRetry from 'axios-retry'
  *
- * const instance = createAxios({ baseURL 'https://api.example.org/' })
+ * const instance = createAxios({ baseURL: 'https://api.example.org/' })
  * axiosRetry(instance, { retries: 3 })
  *
  * await actorCalled('Apisitt')
@@ -189,7 +233,7 @@ import { createAxios } from '../../io';
  * import { axiosCreate } from '@serenity-js/rest'
  * import axiosRetry from 'axios-retry'
  *
- * const instance = axiosCreate({ baseURL 'https://api.example.org/' })
+ * const instance = axiosCreate({ baseURL: 'https://api.example.org/' })
  * axiosRetry(instance, { retries: 3 })
  *
  * await actorCalled('Apisitt')
@@ -505,23 +549,23 @@ function proxyConfigFrom(defaults: AxiosDefaults): AxiosRequestConfigProxyDefaul
 
     const proxyUrl = (defaults.httpAgent as any).getProxyForUrl(defaults.baseURL);
 
-    if (! proxyUrl) {
+    try {
+        const url = new URL(proxyUrl);
+        return {
+            protocol: url.protocol?.replace(/:$/, ''),
+            host:     url.hostname,
+            port:     url.port ? Number(url.port) : undefined,
+            auth:     url.username
+                ? {
+                    username: url.username || undefined,
+                    password: url.password || undefined,
+                }
+                : undefined,
+        };
+    }
+    catch {
         return undefined;
     }
-
-    const url = new URL(proxyUrl);
-
-    return {
-        protocol: url.protocol?.replace(/:$/, ''),
-        host:     url.hostname,
-        port:     url.port ? Number(url.port) : undefined,
-        auth:     url.username
-            ? {
-                username: url.username || undefined,
-                password: url.password || undefined,
-            }
-            : undefined,
-    };
 }
 
 function isUndefined(value: any): value is undefined {

package/lib/io/axiosProxyOverridesFor.d.ts

@@ -1,11 +0,0 @@
-import type * as http from 'http';
-import type { AxiosRequestConfigDefaults } from './AxiosRequestConfigDefaults';
-/**
- * @param options
- */
-export declare function axiosProxyOverridesFor<Data = any>(options: AxiosRequestConfigDefaults<Data>): {
-    proxy: false;
-    httpAgent: http.Agent;
-    httpsAgent: http.Agent;
-};
-//# sourceMappingURL=axiosProxyOverridesFor.d.ts.map