How to Install and Use Shortest for Automated Testing 🚀

Friday, Dec 27, 2024 | 7 minute read

GitHub Trend

Unlock the power of automated testing with this intuitive, AI-driven framework! 🚀 Effortlessly write tests in natural language and enjoy simplicity and speed that boost development efficiency and product quality! 💪✨

In this era of rapid technological advancements, automated testing has become an indispensable part of software development. It not only enhances development efficiency but also ensures high product quality! 💪

1. Shortest: Unlocking the Door to Automated Testing 🔑

@antiwork/shortest is an impressive open-source project that serves as an AI-driven end-to-end (E2E) testing framework. ✨ This incredible initiative aims to significantly improve the testing experience for developers, focusing on usability and high efficiency. Powered by the robust Playwright architecture, users can easily write and execute tests using natural language, making it accessible even for those with limited programming experience! 🎉

As its name suggests, Shortest is a framework that emphasizes simplicity and speed💨, designed to make the testing process more efficient and intuitive, allowing developers to navigate busy projects flexibly and unleash their creativity and productivity.

2. Getting Started with Shortest: Installation and Usage 🎉

Installation

To get started with Shortest, you first need to install it in your project. Just run one of the following commands to complete the installation:

npm install -D @antiwork/shortest
# or
pnpm add -D @antiwork/shortest
# or
yarn add -D @antiwork/shortest

Explanation: By using npm install -D (or similar commands with pnpm or yarn), we add Shortest as a development dependency. The -D flag indicates that it’s marked as a development environment dependency, which means it won’t be installed in production!

After the installation, it’s recommended to add the .shortest/ directory to your version control ignore list to keep your version control clean. Run the following command:

echo ".shortest/" >> .gitignore

Explanation: This command adds the .shortest/ directory to the .gitignore file to prevent inadvertently committing automatically generated temporary files during version control.

Running Tests

Once the installation is complete, we can run our tests! Use one of the following commands:

npx shortest    # for npm
pnpm shortest   # for pnpm
yarn shortest   # for yarn

Explanation: npx is used to execute Node.js package commands, followed by shortest, which is the command we want to run. It’s as simple as that to leverage Shortest’s powerful capabilities!

Quick Start 🚀

Configuring Your Test Entry and Setting API Keys

First, create a configuration file named shortest.config.ts in the root directory of your project. Here’s a simple configuration example:

import type { ShortestConfig } from '@antiwork/shortest';

export default {
  headless: false,
  baseUrl: 'http://localhost:3000',
  testDir: 'app/__tests__',
  anthropicKey: process.env.ANTHROPIC_API_KEY
} satisfies ShortestConfig; 

Explanation: In this configuration object:

• headless: false indicates that tests will run in visible mode, which is particularly useful for debugging.
• baseUrl is the base URL for your application, pointing to the local development environment.
• testDir specifies the directory for your test code (it’s recommended to create an app/__tests__ directory).
• anthropicKey is where you set your API key, ideally read from environment variables to ensure security!

Writing Test Cases 📝

Next, in the app/__tests__/login.test.ts file, add the following code to define a test:

import { shortest } from '@antiwork/shortest'

shortest('Login to the app using email and password', { 
  username: process.env.GITHUB_USERNAME, 
  password: process.env.GITHUB_PASSWORD 
})

Explanation: We import the shortest function and create a new test case. This test will attempt to log in using a GitHub username and password read from environment variables. This method keeps sensitive information separate from the code, protecting our data security.

Using Callback Functions 💻

Shorttest supports customizing test logic with callback functions. Here’s an example:

import { shortest } from '@antiwork/shortest';
import { db } from '@/lib/db/drizzle';
import { users } from '@/lib/db/schema';
import { eq } from 'drizzle-orm';

shortest('Login to the app using username and password', {
  username: process.env.USERNAME,
  password: process.env.PASSWORD
}).after(async ({ page }) => {    
  const clerkId = await page.evaluate(() => {
    return window.localStorage.getItem('clerk-user');
  }); 

  if (!clerkId) {
    throw new Error('User not found in database');
  }

  const [user] = await db
    .select()
    .from(users)
    .where(eq(users.clerkId, clerkId))
    .limit(1);

  expect(user).toBeDefined();
});

Explanation: In this code sample, we run some logic after the test completes using the .after() method. We retrieve clerkId from the browser’s local storage using page.evaluate(), allowing us to verify if the user successfully logged in. Then, we verify the user’s existence by querying the database, ensuring the test’s effectiveness!

Lifecycle Hooks 📅

Using lifecycle hooks, we can execute code at specific moments. Here are some examples:

import { shortest } from '@antiwork/shortest';

shortest.beforeAll(async ({ page }) => {
  await clerkSetup({
    frontendApiUrl: process.env.PLAYWRIGHT_TEST_BASE_URL ?? "http://localhost:3000",
  });
});

shortest.beforeEach(async ({ page }) => {
  await clerk.signIn({
    page,
    signInParams: { 
      strategy: "email_code", 
      identifier: "iffy+clerk_test@example.com" 
    },
  });
});

shortest.afterEach(async ({ page }) => {
  await page.close();
});

shortest.afterAll(async ({ page }) => {
  await clerk.signOut({ page });
});

Explanation: We’ve defined several hook functions:

• beforeAll executes before all tests to set up the environment.
• beforeEach runs before each test to maintain a consistent state.
• afterEach executes after each test to clean up, such as closing pages.
• afterAll handles logic after all tests, like sign-out operations.

Running Tests 🚀

You can run tests using the following commands:

shortest                    # Run all tests
shortest login.test.ts     # Run a specific test
shortest --headless        # Run in headless mode

Explanation: With different command options, you can flexibly choose to run specific tests or run in headless mode, which is particularly useful in CI/CD workflows!

Environment Setup 🌱

Before starting the tests, ensure your .env.local file is configured with environment variables, such as:

ANTHROPIC_API_KEY=your_api_key
GITHUB_TOTP_SECRET=your_secret  # Only for GitHub authentication tests

Explanation: ANTHROPIC_API_KEY connects to the related API, and GITHUB_TOTP_SECRET is the multi-factor authentication key, especially useful for logging into GitHub.

Local Development Setup Guide 🛠️

Prerequisites ⚙️

• Ensure you have React version >=19.0.0 installed.
• Ensure you have Next.js version >=14.0.0 installed.

Getting Started 🏁

1. Clone the Shortest repository:

git clone https://github.com/anti-work/shortest.git
cd shortest

Explanation: This command downloads the code repository to your local machine and navigates into the folder, kickstarting your exploration!

2. Install the dependencies:

npm install -g pnpm
pnpm install

Explanation: First, install pnpm globally, then use it to install the project dependencies. This ensures all libraries are properly set up in your local environment!

Setting Up the Database 📦

pnpm drizzle-kit generate
pnpm db:migrate
pnpm db:seed

Explanation: These commands initialize the database, migrate the structure, and populate it with baseline data, preparing the testing environment!

Running the Application 🖥️

To start the local development server, use this command:

pnpm dev

Explanation: Running this command will start the Next.js development server, allowing you to access the application in your local environment, typically at http://localhost:3000 in your browser.

Building the Shortest Package ⚙️

pnpm build:pkg
pnpm install

Explanation: These commands build the Shortest package and install it, ensuring you have the latest version built locally! 😊

Setting Up the Shortest CLI for Local Development 📏

cd packages/shortest
pnpm link --global

cd ../..
pnpm link --global shortest

Explanation: These commands set up the Shortest CLI to be globally accessible, making it easy to invoke from the command line anywhere!

Local Testing of the CLI 🧪

1. Create a temporary test directory:

cd ~/shortest-test

Explanation: Quickly navigate to the user home directory and create a temporary directory for testing.

2. Locally package the Shortest package:

cd /packages/shortest
pnpm pack

Explanation: This command packages the project within the Shortest package, generating a .tgz file for later local installation.

3. Install the packaged tarball in your testing directory:

cd ~/test-cli
npm init -y
npm install ../packages/shortest/antiwork-shortest-{version}.tgz

Explanation: Initialize a new npm project and install the tarball generated from the previous step, making it easy to get started with your testing!

4. Test the CLI:

npx shortest -h

Explanation: Running this command will display the help information for the Shortest CLI, ensuring everything is functioning correctly. With these steps, you can begin fun and engaging automated testing with Shortest! 🎊