overhaul of test filtering + some bug fixes

Author: toptobes

.env.example

@@ -1,5 +1,14 @@
-# Astra API endpoint (THIS IS FOR RUNNING THE TESTS, NOT FOR BASIC CLIENT USAGE)
+# Astra API endpoint
 ASTRA_URI=https://<db_id>-<region>.apps.astra.datastax.com
 
-# Application token, used to authenticate with the Astra API (THIS IS FOR RUNNING THE TESTS, NOT FOR BASIC CLIENT USAGE)
+# Application token, used to authenticate with the Astra API
 APPLICATION_TOKEN=AstraCS:<rest_of_token>
+
+# Set this to some value to enable running tests that require a dev environment (make sure you're actually using the dev environment!!)
+ASTRA_RUN_DEV_TESTS=
+
+# Set this to some value to enable running long-running tests
+ASTRA_RUN_LONG_TESTS=
+
+# Set this to some value to enable running admin tests
+ASTRA_RUN_ADMIN_TESTS=

DEVGUIDE.md

@@ -26,12 +26,44 @@ npm run test:coverage
 npm run test:types
 ```
 
-I heavily recommend filtering out the tag `[long]` when you're just doing some smoke-ish testing.
+### Running tagged tests
+Tests can be given certain tags to allow for more granular control over which tests are run. These tags currently include:
+- `[long]`/`'LONG'`: Longer running tests that take more than a few seconds to run
+- `[admin]`/`'ADMIN'`: Tests that require admin permissions to run
+- `[dev]`/`'DEV'`: Tests that require the dev environment to run
+
+To enable these tags, you can set the corresponding environment variables to some values. The env variables are in the
+`env.example` file, but they're repeated here for convenience:
+- `ASTRA_RUN_DEV_TESTS`
+- `ASTRA_RUN_LONG_TESTS`
+- `ASTRA_RUN_ADMIN_TESTS`
+
+Or you can run the tests by doing something like
 ```shell
-npm run test -- -f [long] -i
+env ASTRA_RUN_LONG_TESTS=1 npm run test
+```
+
+### Adding your own tagged tests
+To enforce the tags, use the `assertTestsEnabled` function from `test/fixtures.ts`, which will skip the function if the
+given tag is not enabled. 
+
+It's also encouraged to add the corresponding tag to the test name, so that it's clear why the test is being skipped.
+
+For example:
+```typescript
+describe('[long] createCollection + dropCollection', () => {
+  // Note that it's important to use an actual function here, not an arrow function
+  before(async function () {
+    assertTestsEnabled(this, 'LONG');
+  });
+
+  // ...
+});
 ```
 
-If you're adding a test, that isn't absolutely essential, that takes over ~2-3 seconds to run, please add the `[long]` tag to it.
+If a new tag really, really, needs to be added, it can be done by adding a new environment variable of the proper
+format, and updating the `assertTestsEnabled` function. However, this should be done sparingly, as it can make the
+test suite harder to manage.
 
 ### Linting
 Run `npm run lint` to run ESLint.

src/data-api/collection.ts

@@ -177,6 +177,10 @@ export class Collection<Schema extends SomeDoc = SomeDoc> {
       insertOne: { document },
     }
 
+    if (options?.vector && options?.vectorize) {
+      throw new Error('Cannot set both vector and vectorize options');
+    }
+
     if (options?.vector) {
       command.insertOne.document = { ...command.insertOne.document, $vector: options.vector };
     }
@@ -268,6 +272,10 @@ export class Collection<Schema extends SomeDoc = SomeDoc> {
   async insertMany(documents: MaybeId<Schema>[], options?: InsertManyOptions): Promise<InsertManyResult<Schema>> {
     const chunkSize = options?.chunkSize ?? 20;
 
+    if (options?.vectors && options?.vectorize) {
+      throw new Error('Cannot set both vectors and vectorize options');
+    }
+
     if (options?.vectors) {
       if (options.vectors.length !== documents.length) {
         throw new Error('The number of vectors must match the number of documents');

src/data-api/types/utils.ts

@@ -21,6 +21,8 @@ import type { SomeId } from '@/src/data-api/types';
  * ```
  * IsNum<string | number> === true
  * ```
+ *
+ * @internal
  */
 export type IsNum<T> = number extends T ? true : bigint extends T ? true : false
 
@@ -31,9 +33,16 @@ export type IsNum<T> = number extends T ? true : bigint extends T ? true : false
  * ```
  * IsDate<string | Date> === boolean
  * ```
+ *
+ * @internal
  */
 export type IsDate<T> = IsAny<T> extends true ? true : T extends Date | { $date: number } ? true : false
 
+/**
+ * Checks if a type is any
+ *
+ * @internal
+ */
 export type IsAny<T> = true extends false & T ? true : false
 
 /**
@@ -81,6 +90,8 @@ export type IdOf<TSchema> =
 
 /**
  * Makes all fields in a type mutable
+ *
+ * @internal
  */
 export type Mutable<T> = {
   -readonly [P in keyof T]: T[P];

src/devops/astra-admin.ts

@@ -1,6 +1,6 @@
 import { AdminBlockingOptions, DatabaseConfig, FullDatabaseInfo, ListDatabasesOptions } from '@/src/devops/types';
 import { Db, mkDb } from '@/src/data-api';
-import { DEFAULT_DEVOPS_API_ENDPOINT, DevopsApiHttpClient, HTTP_METHODS } from '@/src/api';
+import { DEFAULT_DEVOPS_API_ENDPOINT, DEFAULT_NAMESPACE, DevopsApiHttpClient, HTTP_METHODS } from '@/src/api';
 import { AstraDbAdmin } from '@/src/devops/astra-db-admin';
 import { AdminSpawnOptions, DbSpawnOptions, RootClientOptsWithToken } from '@/src/client/types';
 
@@ -59,26 +59,29 @@ export class AstraAdmin {
   }
 
   public async createDatabase(config: DatabaseConfig, options?: AdminBlockingOptions): Promise<AstraDbAdmin> {
+    const definition = {
+      capacityUnits: 1,
+      tier: 'serverless',
+      dbType: 'vector',
+      keyspace: config.namespace || DEFAULT_NAMESPACE,
+      ...config,
+    }
+
     const resp = await this._httpClient.request({
       method: HTTP_METHODS.Post,
       path: '/databases',
-      data: {
-        capacityUnits: 1,
-        tier: 'serverless',
-        dbType: 'vector',
-        ...config,
-      },
+      data: definition,
     });
 
-    const db = mkDb(this.#defaultOpts, resp.headers.location, config.region, { namespace: resp.data.info.keyspace });
+    const db = mkDb(this.#defaultOpts, resp.headers.location, definition.region, { namespace: definition.keyspace });
     const admin = db.admin(this.#defaultOpts.devopsOptions);
 
     await this._httpClient.awaitStatus(db, 'ACTIVE', ['INITIALIZING', 'PENDING'], options, 10000);
     return admin;
   }
 
-  async dropDatabase(_db: Db | string, options?: AdminBlockingOptions): Promise<void> {
-    const id = typeof _db === 'string' ? _db : _db.id;
+  async dropDatabase(db: Db | string, options?: AdminBlockingOptions): Promise<void> {
+    const id = typeof db === 'string' ? db : db.id;
 
     await this._httpClient.request({
       method: HTTP_METHODS.Post,

src/devops/types/admin/create-database.ts

@@ -34,6 +34,10 @@ export interface DatabaseConfig {
    * The cloud region where the database is located.
    */
   region: string,
+  /**
+   * The default namespace to use for the database.
+   */
+  namespace?: string,
 }
 
 export type AdminBlockingOptions =

src/devops/types/admin/list-databases.ts

@@ -26,7 +26,7 @@ export interface ListDatabasesOptions {
   /**
    * Allows filtering so that databases in listed states are returned.
    */
-  include?: Lowercase<DatabaseStatus>,
+  include?: DatabaseStatus,
   /**
    * Allows filtering so that databases from a given provider are returned.
    */
@@ -36,6 +36,8 @@ export interface ListDatabasesOptions {
    *
    * Should be between 1 and 100.
    *
+   * Defaults to 25.
+   *
    * @defaultValue 25
    */
   limit?: number,