mirror of
https://github.com/documenso/documenso.git
synced 2026-07-14 06:47:10 +10:00
chore: add embed envelope docs (#2576)
This commit is contained in:
David Nguyen
GitHub
@@ -0,0 +1,27 @@
|
||||
---
|
||||
description: Generate markdown documentation for a module or feature
|
||||
argument-hint: <topic-or-feature>
|
||||
---
|
||||
|
||||
You are generating documentation for the Documenso project.
|
||||
|
||||
## Your Task
|
||||
|
||||
Load and follow the skill at `.agents/skills/create-documentation/SKILL.md`. It contains the complete instructions for writing documentation including:
|
||||
|
||||
- Documentation structure and file locations
|
||||
- MDX format and Fumadocs components
|
||||
- Audience-specific patterns (Users, Developers, Self-Hosters)
|
||||
- Navigation (`meta.json`) updates
|
||||
- Writing style guidelines
|
||||
|
||||
## Context
|
||||
|
||||
The topic or feature to document is: `$ARGUMENTS`
|
||||
|
||||
## Begin
|
||||
|
||||
1. **Read the skill** at `.agents/skills/create-documentation/SKILL.md`
|
||||
2. **Read WRITING_STYLE.md** for tone and formatting conventions
|
||||
3. **Follow the skill instructions** to create comprehensive documentation
|
||||
4. **Use TodoWrite** to track your progress throughout
|
||||
@@ -7,69 +7,17 @@ You are creating a new justification file in the `.agents/justifications/` direc
|
||||
|
||||
## Your Task
|
||||
|
||||
1. **Determine the slug** - Use `$ARGUMENTS` as the file slug (kebab-case recommended)
|
||||
2. **Gather content** - Collect or generate the justification content
|
||||
3. **Create the file** - Use the create-justification script to generate the file
|
||||
Load and follow the skill at `.agents/skills/create-justification/SKILL.md`. It contains the complete instructions for creating justification files including:
|
||||
|
||||
## Usage
|
||||
- Unique three-word ID generation
|
||||
- Frontmatter format with date and title
|
||||
- Script usage (`scripts/create-justification.ts`)
|
||||
|
||||
The script will automatically:
|
||||
- Generate a unique three-word ID (e.g., `swift-emerald-river`)
|
||||
- Create frontmatter with current date and formatted title
|
||||
- Save the file as `{id}-{slug}.md` in `.agents/justifications/`
|
||||
## Context
|
||||
|
||||
## Creating the File
|
||||
|
||||
### Option 1: Direct Content
|
||||
|
||||
If you have the content ready, run:
|
||||
|
||||
```bash
|
||||
npx tsx scripts/create-justification.ts "$ARGUMENTS" "Your justification content here"
|
||||
```
|
||||
|
||||
### Option 2: Multi-line Content (Heredoc)
|
||||
|
||||
For multi-line content, use heredoc:
|
||||
|
||||
```bash
|
||||
npx tsx scripts/create-justification.ts "$ARGUMENTS" << HEREDOC
|
||||
Your multi-line
|
||||
justification content
|
||||
goes here
|
||||
HEREDOC
|
||||
```
|
||||
|
||||
### Option 3: Pipe Content
|
||||
|
||||
You can also pipe content:
|
||||
|
||||
```bash
|
||||
echo "Your content" | npx tsx scripts/create-justification.ts "$ARGUMENTS"
|
||||
```
|
||||
|
||||
## File Format
|
||||
|
||||
The created file will have:
|
||||
|
||||
```markdown
|
||||
---
|
||||
date: 2026-01-13
|
||||
title: Justification Title
|
||||
---
|
||||
|
||||
Your content here
|
||||
```
|
||||
|
||||
The title is automatically formatted from the slug (e.g., `architecture-decision` → `Architecture Decision`).
|
||||
|
||||
## Guidelines
|
||||
|
||||
- Use descriptive slugs in kebab-case (e.g., `tech-stack-choice`, `api-design-rationale`)
|
||||
- Include clear reasoning and context for the decision
|
||||
- The unique ID ensures no filename conflicts
|
||||
- Files are automatically dated for organization
|
||||
The justification slug and optional content: `$ARGUMENTS`
|
||||
|
||||
## Begin
|
||||
|
||||
Create a justification file using the slug from `$ARGUMENTS` and appropriate content documenting the reasoning or justification.
|
||||
1. **Read the skill** at `.agents/skills/create-justification/SKILL.md`
|
||||
2. **Create the justification file** using the slug from `$ARGUMENTS` and appropriate content documenting the reasoning or justification
|
||||
|
||||
@@ -7,70 +7,17 @@ You are creating a new plan file in the `.agents/plans/` directory.
|
||||
|
||||
## Your Task
|
||||
|
||||
1. **Determine the slug** - Use `$ARGUMENTS` as the file slug (kebab-case recommended)
|
||||
2. **Gather content** - Collect or generate the plan content
|
||||
3. **Create the file** - Use the create-plan script to generate the file
|
||||
Load and follow the skill at `.agents/skills/create-plan/SKILL.md`. It contains the complete instructions for creating plan files including:
|
||||
|
||||
## Usage
|
||||
- Unique three-word ID generation
|
||||
- Frontmatter format with date and title
|
||||
- Script usage (`scripts/create-plan.ts`)
|
||||
|
||||
The script will automatically:
|
||||
## Context
|
||||
|
||||
- Generate a unique three-word ID (e.g., `happy-blue-moon`)
|
||||
- Create frontmatter with current date and formatted title
|
||||
- Save the file as `{id}-{slug}.md` in `.agents/plans/`
|
||||
|
||||
## Creating the File
|
||||
|
||||
### Option 1: Direct Content
|
||||
|
||||
If you have the content ready, run:
|
||||
|
||||
```bash
|
||||
npx tsx scripts/create-plan.ts "$ARGUMENTS" "Your plan content here"
|
||||
```
|
||||
|
||||
### Option 2: Multi-line Content (Heredoc)
|
||||
|
||||
For multi-line content, use heredoc:
|
||||
|
||||
```bash
|
||||
npx tsx scripts/create-plan.ts "$ARGUMENTS" << HEREDOC
|
||||
Your multi-line
|
||||
plan content
|
||||
goes here
|
||||
HEREDOC
|
||||
```
|
||||
|
||||
### Option 3: Pipe Content
|
||||
|
||||
You can also pipe content:
|
||||
|
||||
```bash
|
||||
echo "Your content" | npx tsx scripts/create-plan.ts "$ARGUMENTS"
|
||||
```
|
||||
|
||||
## File Format
|
||||
|
||||
The created file will have:
|
||||
|
||||
```markdown
|
||||
---
|
||||
date: 2026-01-13
|
||||
title: Plan Title
|
||||
---
|
||||
|
||||
Your content here
|
||||
```
|
||||
|
||||
The title is automatically formatted from the slug (e.g., `my-feature` → `My Feature`).
|
||||
|
||||
## Guidelines
|
||||
|
||||
- Use descriptive slugs in kebab-case (e.g., `user-authentication`, `api-integration`)
|
||||
- Include clear, actionable plan content
|
||||
- The unique ID ensures no filename conflicts
|
||||
- Files are automatically dated for organization
|
||||
The plan slug and optional content: `$ARGUMENTS`
|
||||
|
||||
## Begin
|
||||
|
||||
Create a plan file using the slug from `$ARGUMENTS` and appropriate content for the planning task.
|
||||
1. **Read the skill** at `.agents/skills/create-plan/SKILL.md`
|
||||
2. **Create the plan file** using the slug from `$ARGUMENTS` and appropriate content
|
||||
|
||||
@@ -7,69 +7,17 @@ You are creating a new scratch file in the `.agents/scratches/` directory.
|
||||
|
||||
## Your Task
|
||||
|
||||
1. **Determine the slug** - Use `$ARGUMENTS` as the file slug (kebab-case recommended)
|
||||
2. **Gather content** - Collect or generate the scratch content
|
||||
3. **Create the file** - Use the create-scratch script to generate the file
|
||||
Load and follow the skill at `.agents/skills/create-scratch/SKILL.md`. It contains the complete instructions for creating scratch files including:
|
||||
|
||||
## Usage
|
||||
- Unique three-word ID generation
|
||||
- Frontmatter format with date and title
|
||||
- Script usage (`scripts/create-scratch.ts`)
|
||||
|
||||
The script will automatically:
|
||||
- Generate a unique three-word ID (e.g., `calm-teal-cloud`)
|
||||
- Create frontmatter with current date and formatted title
|
||||
- Save the file as `{id}-{slug}.md` in `.agents/scratches/`
|
||||
## Context
|
||||
|
||||
## Creating the File
|
||||
|
||||
### Option 1: Direct Content
|
||||
|
||||
If you have the content ready, run:
|
||||
|
||||
```bash
|
||||
npx tsx scripts/create-scratch.ts "$ARGUMENTS" "Your scratch content here"
|
||||
```
|
||||
|
||||
### Option 2: Multi-line Content (Heredoc)
|
||||
|
||||
For multi-line content, use heredoc:
|
||||
|
||||
```bash
|
||||
npx tsx scripts/create-scratch.ts "$ARGUMENTS" << HEREDOC
|
||||
Your multi-line
|
||||
scratch content
|
||||
goes here
|
||||
HEREDOC
|
||||
```
|
||||
|
||||
### Option 3: Pipe Content
|
||||
|
||||
You can also pipe content:
|
||||
|
||||
```bash
|
||||
echo "Your content" | npx tsx scripts/create-scratch.ts "$ARGUMENTS"
|
||||
```
|
||||
|
||||
## File Format
|
||||
|
||||
The created file will have:
|
||||
|
||||
```markdown
|
||||
---
|
||||
date: 2026-01-13
|
||||
title: Scratch Title
|
||||
---
|
||||
|
||||
Your content here
|
||||
```
|
||||
|
||||
The title is automatically formatted from the slug (e.g., `quick-notes` → `Quick Notes`).
|
||||
|
||||
## Guidelines
|
||||
|
||||
- Use descriptive slugs in kebab-case (e.g., `exploration-ideas`, `temporary-notes`)
|
||||
- Scratch files are for temporary notes, explorations, or ideas
|
||||
- The unique ID ensures no filename conflicts
|
||||
- Files are automatically dated for organization
|
||||
The scratch slug and optional content: `$ARGUMENTS`
|
||||
|
||||
## Begin
|
||||
|
||||
Create a scratch file using the slug from `$ARGUMENTS` and appropriate content for notes or exploration.
|
||||
1. **Read the skill** at `.agents/skills/create-scratch/SKILL.md`
|
||||
2. **Create the scratch file** using the slug from `$ARGUMENTS` and appropriate content for notes or exploration
|
||||
|
||||
@@ -1,201 +0,0 @@
|
||||
---
|
||||
description: Generate MDX documentation for a module or feature
|
||||
argument-hint: <module-path-or-feature>
|
||||
---
|
||||
|
||||
You are creating proper MDX documentation for a module or feature in Documenso using Nextra.
|
||||
|
||||
## Your Task
|
||||
|
||||
1. **Identify the scope** - What does `$ARGUMENTS` refer to? (file, directory, or feature name)
|
||||
2. **Read the source code** - Understand the public API, types, and behavior
|
||||
3. **Read existing docs** - Check if there's documentation to update or reference
|
||||
4. **Write comprehensive documentation** - Create or update MDX docs in the appropriate location
|
||||
5. **Update navigation** - Add entry to `_meta.js` if creating a new page
|
||||
|
||||
## Documentation Structure
|
||||
|
||||
Create documentation in the appropriate location:
|
||||
|
||||
- **Developer docs**: `apps/documentation/pages/developers/`
|
||||
- **User docs**: `apps/documentation/pages/users/`
|
||||
|
||||
### File Format
|
||||
|
||||
All documentation files must be `.mdx` files with frontmatter:
|
||||
|
||||
```mdx
|
||||
---
|
||||
title: Page Title
|
||||
description: Brief description for SEO and meta tags
|
||||
---
|
||||
|
||||
# Page Title
|
||||
|
||||
Content starts here...
|
||||
```
|
||||
|
||||
### Navigation
|
||||
|
||||
Each directory should have a `_meta.js` file that defines the navigation structure:
|
||||
|
||||
```javascript
|
||||
export default {
|
||||
index: 'Introduction',
|
||||
'feature-name': 'Feature Name',
|
||||
'another-feature': 'Another Feature',
|
||||
};
|
||||
```
|
||||
|
||||
If creating a new page, add it to the appropriate `_meta.js` file.
|
||||
|
||||
### Documentation Format
|
||||
|
||||
````mdx
|
||||
---
|
||||
title: <Module|Feature Name>
|
||||
description: Brief description of what this does and when to use it
|
||||
---
|
||||
|
||||
# <Module|Feature Name>
|
||||
|
||||
Brief description of what this module/feature does and when to use it.
|
||||
|
||||
## Installation
|
||||
|
||||
If there are specific packages or imports needed:
|
||||
|
||||
```bash
|
||||
npm install @documenso/package-name
|
||||
```
|
||||
|
||||
## Quick Start
|
||||
|
||||
```jsx
|
||||
// Minimal working example
|
||||
import { Component } from '@documenso/package';
|
||||
|
||||
const Example = () => {
|
||||
return <Component />;
|
||||
};
|
||||
```
|
||||
|
||||
## API Reference
|
||||
|
||||
### Component/Function Name
|
||||
|
||||
Description of what it does.
|
||||
|
||||
#### Props/Parameters
|
||||
|
||||
| Prop/Param | Type | Description |
|
||||
| ---------- | -------------------- | ------------------------- |
|
||||
| prop | `string` | Description of the prop |
|
||||
| optional | `boolean` (optional) | Optional prop description |
|
||||
|
||||
#### Example
|
||||
|
||||
```jsx
|
||||
import { Component } from '@documenso/package';
|
||||
|
||||
<Component prop="value" optional={true} />;
|
||||
```
|
||||
|
||||
### Types
|
||||
|
||||
#### `TypeName`
|
||||
|
||||
```typescript
|
||||
type TypeName = {
|
||||
property: string;
|
||||
optional?: boolean;
|
||||
};
|
||||
```
|
||||
|
||||
## Examples
|
||||
|
||||
### Common Use Case
|
||||
|
||||
```jsx
|
||||
// Full working example
|
||||
```
|
||||
|
||||
### Advanced Usage
|
||||
|
||||
```jsx
|
||||
// More complex example
|
||||
```
|
||||
|
||||
## Related
|
||||
|
||||
- [Link to related documentation](/developers/path)
|
||||
- [Another related page](/users/path)
|
||||
````
|
||||
|
||||
## Guidelines
|
||||
|
||||
### Content Quality
|
||||
|
||||
- **Be accurate** - Verify behavior by reading the code
|
||||
- **Be complete** - Document all public API surface
|
||||
- **Be practical** - Include real, working examples
|
||||
- **Be concise** - Don't over-explain obvious things
|
||||
- **Be user-focused** - Write for the target audience (developers or users)
|
||||
|
||||
### Code Examples
|
||||
|
||||
- Use appropriate language tags: `jsx`, `tsx`, `typescript`, `bash`, `json`
|
||||
- Show imports when not obvious
|
||||
- Include expected output in comments where helpful
|
||||
- Progress from simple to complex
|
||||
- Use real examples from the codebase when possible
|
||||
|
||||
### Formatting
|
||||
|
||||
- Always include frontmatter with `title` and `description`
|
||||
- Use proper markdown headers (h1 for title, h2 for sections)
|
||||
- Use tables for props/parameters documentation (matching existing style)
|
||||
- Use code fences with appropriate language tags
|
||||
- Use Nextra components when appropriate:
|
||||
- `<Callout type="info">` for notes
|
||||
- `<Steps>` for step-by-step instructions
|
||||
- Use relative links for internal documentation (e.g., `/developers/embedding/react`)
|
||||
|
||||
### Nextra Components
|
||||
|
||||
You can import and use Nextra components:
|
||||
|
||||
```jsx
|
||||
import { Callout, Steps } from 'nextra/components';
|
||||
|
||||
<Callout type="info">
|
||||
This is an informational note.
|
||||
</Callout>
|
||||
|
||||
<Steps>
|
||||
<Steps.Step>First step</Steps.Step>
|
||||
<Steps.Step>Second step</Steps.Step>
|
||||
</Steps>
|
||||
```
|
||||
|
||||
### Maintenance
|
||||
|
||||
- Include types inline so docs don't get stale
|
||||
- Reference source file locations for complex behavior
|
||||
- Keep examples up-to-date with the codebase
|
||||
- Update `_meta.js` when adding new pages
|
||||
|
||||
## Process
|
||||
|
||||
1. **Explore the code** - Read source files to understand the API
|
||||
2. **Identify the audience** - Is this for developers or users?
|
||||
3. **Check existing docs** - Look for similar pages to match style
|
||||
4. **Draft the structure** - Outline sections before writing
|
||||
5. **Write content** - Fill in each section with frontmatter
|
||||
6. **Add examples** - Create working code samples
|
||||
7. **Update navigation** - Add to `_meta.js` if needed
|
||||
8. **Review** - Read through for clarity and accuracy
|
||||
|
||||
## Begin
|
||||
|
||||
Analyze `$ARGUMENTS`, read the relevant source code, check existing documentation patterns, and create comprehensive MDX documentation following the Documenso documentation style.
|
||||
@@ -1,56 +0,0 @@
|
||||
---
|
||||
name: create-justification
|
||||
description: Create a new justification file in .agents/justifications/ with a unique three-word ID, frontmatter, and formatted title
|
||||
license: MIT
|
||||
compatibility: opencode
|
||||
metadata:
|
||||
audience: agents
|
||||
workflow: decision-making
|
||||
---
|
||||
|
||||
## What I do
|
||||
|
||||
I help you create new justification files in the `.agents/justifications/` directory. Each justification file gets:
|
||||
|
||||
- A unique three-word identifier (e.g., `swift-emerald-river`)
|
||||
- Frontmatter with the current date and formatted title
|
||||
- Content you provide
|
||||
|
||||
## How to use
|
||||
|
||||
Run the script with a slug and content:
|
||||
|
||||
```bash
|
||||
npx tsx scripts/create-justification.ts "decision-name" "Justification content here"
|
||||
```
|
||||
|
||||
Or use heredoc for multi-line content:
|
||||
|
||||
```bash
|
||||
npx tsx scripts/create-justification.ts "decision-name" << HEREDOC
|
||||
Multi-line
|
||||
justification content
|
||||
goes here
|
||||
HEREDOC
|
||||
```
|
||||
|
||||
## File format
|
||||
|
||||
Files are created as: `{three-word-id}-{slug}.md`
|
||||
|
||||
Example: `swift-emerald-river-decision-name.md`
|
||||
|
||||
The file includes frontmatter:
|
||||
|
||||
```markdown
|
||||
---
|
||||
date: 2026-01-13
|
||||
title: Decision Name
|
||||
---
|
||||
|
||||
Your content here
|
||||
```
|
||||
|
||||
## When to use me
|
||||
|
||||
Use this skill when you need to document the reasoning or justification for a decision, approach, or architectural choice. The unique ID ensures no filename conflicts, and the frontmatter provides metadata for organization.
|
||||
@@ -1,56 +0,0 @@
|
||||
---
|
||||
name: create-plan
|
||||
description: Create a new plan file in .agents/plans/ with a unique three-word ID, frontmatter, and formatted title
|
||||
license: MIT
|
||||
compatibility: opencode
|
||||
metadata:
|
||||
audience: agents
|
||||
workflow: planning
|
||||
---
|
||||
|
||||
## What I do
|
||||
|
||||
I help you create new plan files in the `.agents/plans/` directory. Each plan file gets:
|
||||
|
||||
- A unique three-word identifier (e.g., `happy-blue-moon`)
|
||||
- Frontmatter with the current date and formatted title
|
||||
- Content you provide
|
||||
|
||||
## How to use
|
||||
|
||||
Run the script with a slug and content:
|
||||
|
||||
```bash
|
||||
npx tsx scripts/create-plan.ts "feature-name" "Plan content here"
|
||||
```
|
||||
|
||||
Or use heredoc for multi-line content:
|
||||
|
||||
```bash
|
||||
npx tsx scripts/create-plan.ts "feature-name" << HEREDOC
|
||||
Multi-line
|
||||
plan content
|
||||
goes here
|
||||
HEREDOC
|
||||
```
|
||||
|
||||
## File format
|
||||
|
||||
Files are created as: `{three-word-id}-{slug}.md`
|
||||
|
||||
Example: `happy-blue-moon-feature-name.md`
|
||||
|
||||
The file includes frontmatter:
|
||||
|
||||
```markdown
|
||||
---
|
||||
date: 2026-01-13
|
||||
title: Feature Name
|
||||
---
|
||||
|
||||
Your content here
|
||||
```
|
||||
|
||||
## When to use me
|
||||
|
||||
Use this skill when you need to create a new plan document for a feature, task, or project. The unique ID ensures no filename conflicts, and the frontmatter provides metadata for organization.
|
||||
@@ -1,56 +0,0 @@
|
||||
---
|
||||
name: create-scratch
|
||||
description: Create a new scratch file in .agents/scratches/ with a unique three-word ID, frontmatter, and formatted title
|
||||
license: MIT
|
||||
compatibility: opencode
|
||||
metadata:
|
||||
audience: agents
|
||||
workflow: exploration
|
||||
---
|
||||
|
||||
## What I do
|
||||
|
||||
I help you create new scratch files in the `.agents/scratches/` directory. Each scratch file gets:
|
||||
|
||||
- A unique three-word identifier (e.g., `calm-teal-cloud`)
|
||||
- Frontmatter with the current date and formatted title
|
||||
- Content you provide
|
||||
|
||||
## How to use
|
||||
|
||||
Run the script with a slug and content:
|
||||
|
||||
```bash
|
||||
npx tsx scripts/create-scratch.ts "note-name" "Scratch content here"
|
||||
```
|
||||
|
||||
Or use heredoc for multi-line content:
|
||||
|
||||
```bash
|
||||
npx tsx scripts/create-scratch.ts "note-name" << HEREDOC
|
||||
Multi-line
|
||||
scratch content
|
||||
goes here
|
||||
HEREDOC
|
||||
```
|
||||
|
||||
## File format
|
||||
|
||||
Files are created as: `{three-word-id}-{slug}.md`
|
||||
|
||||
Example: `calm-teal-cloud-note-name.md`
|
||||
|
||||
The file includes frontmatter:
|
||||
|
||||
```markdown
|
||||
---
|
||||
date: 2026-01-13
|
||||
title: Note Name
|
||||
---
|
||||
|
||||
Your content here
|
||||
```
|
||||
|
||||
## When to use me
|
||||
|
||||
Use this skill when you need to create a temporary note, exploration document, or scratch pad for ideas. The unique ID ensures no filename conflicts, and the frontmatter provides metadata for organization.
|
||||
@@ -1 +0,0 @@
|
||||
../../.agents/skills/agent-browser
|
||||
@@ -1,371 +0,0 @@
|
||||
---
|
||||
name: envelope-editor-v2-e2e
|
||||
description: Writing and maintaining Playwright E2E tests for the Envelope Editor V2. Use when the user needs to create, modify, debug, or extend E2E tests in packages/app-tests/e2e/envelope-editor-v2/. Triggers include requests to "write an e2e test", "add a test for the envelope editor", "test envelope settings/recipients/fields/items/attachments", "fix a failing envelope test", or any task involving Playwright tests for the envelope editor feature.
|
||||
---
|
||||
|
||||
# Envelope Editor V2 E2E Tests
|
||||
|
||||
## Overview
|
||||
|
||||
The Envelope Editor V2 E2E test suite lives in `packages/app-tests/e2e/envelope-editor-v2/`. Each test file covers a distinct feature area of the envelope editor and follows a strict architectural pattern that tests the **same flow** across four surfaces:
|
||||
|
||||
1. **Document** (`documents/<id>`) - Native document editor
|
||||
2. **Template** (`templates/<id>`) - Native template editor
|
||||
3. **Embedded Create** (`/embed/v2/authoring/envelope/create`) - Embedded editor creating a new envelope
|
||||
4. **Embedded Edit** (`/embed/v2/authoring/envelope/edit/<id>`) - Embedded editor updating an existing envelope
|
||||
|
||||
## Project Structure
|
||||
|
||||
```
|
||||
packages/app-tests/
|
||||
e2e/
|
||||
envelope-editor-v2/
|
||||
envelope-attachments.spec.ts # Attachment CRUD
|
||||
envelope-fields.spec.ts # Field placement on PDF canvas
|
||||
envelope-items.spec.ts # PDF document item CRUD
|
||||
envelope-recipients.spec.ts # Recipient management
|
||||
envelope-settings.spec.ts # Settings dialog
|
||||
fixtures/
|
||||
authentication.ts # apiSignin, apiSignout
|
||||
documents.ts # Document tab helpers
|
||||
envelope-editor.ts # Core fixture: surface openers + locator/action helpers
|
||||
generic.ts # Toast assertions, text visibility
|
||||
signature.ts # Signature pad helpers
|
||||
playwright.config.ts # Test configuration
|
||||
```
|
||||
|
||||
## Core Abstraction: `TEnvelopeEditorSurface`
|
||||
|
||||
Every test revolves around the `TEnvelopeEditorSurface` type from `fixtures/envelope-editor.ts`. This is the central abstraction that normalizes differences between the four surfaces:
|
||||
|
||||
```typescript
|
||||
type TEnvelopeEditorSurface = {
|
||||
root: Page; // The Playwright page
|
||||
isEmbedded: boolean; // true for embed surfaces
|
||||
envelopeId?: string; // Set for document/template/embed-edit, undefined for embed-create
|
||||
envelopeType: 'DOCUMENT' | 'TEMPLATE';
|
||||
userId: number; // Seeded user ID
|
||||
userEmail: string; // Seeded user email
|
||||
userName: string; // Seeded user name
|
||||
teamId: number; // Seeded team ID
|
||||
};
|
||||
```
|
||||
|
||||
### Surface Openers (from `fixtures/envelope-editor.ts`)
|
||||
|
||||
```typescript
|
||||
// Native surfaces - seed user + document/template, sign in, navigate
|
||||
const surface = await openDocumentEnvelopeEditor(page);
|
||||
const surface = await openTemplateEnvelopeEditor(page);
|
||||
|
||||
// Embedded surfaces - seed user, create API token, get presign token, navigate
|
||||
const surface = await openEmbeddedEnvelopeEditor(page, {
|
||||
envelopeType: 'DOCUMENT' | 'TEMPLATE',
|
||||
mode?: 'create' | 'edit', // default: 'create'
|
||||
tokenNamePrefix?: string, // for unique API token names
|
||||
externalId?: string, // optional external ID in hash
|
||||
features?: EmbeddedEditorConfig, // feature flags
|
||||
});
|
||||
```
|
||||
|
||||
## Test Architecture Pattern
|
||||
|
||||
Every test file follows this structure, with four `test.describe` blocks grouping tests by editor surface:
|
||||
|
||||
### 1. Imports
|
||||
|
||||
```typescript
|
||||
import { type Page, expect, test } from '@playwright/test';
|
||||
// Prisma enums if needed for DB assertions
|
||||
import { SomePrismaEnum } from '@prisma/client';
|
||||
|
||||
import { nanoid } from '@documenso/lib/universal/id';
|
||||
import { prisma } from '@documenso/prisma';
|
||||
|
||||
import {
|
||||
type TEnvelopeEditorSurface, // Import needed helpers from the fixture
|
||||
openDocumentEnvelopeEditor,
|
||||
openEmbeddedEnvelopeEditor,
|
||||
openTemplateEnvelopeEditor,
|
||||
persistEmbeddedEnvelope, // ... other helpers
|
||||
} from '../fixtures/envelope-editor';
|
||||
import { expectToastTextToBeVisible } from '../fixtures/generic';
|
||||
```
|
||||
|
||||
### 2. Type definitions and constants
|
||||
|
||||
```typescript
|
||||
type FlowResult = {
|
||||
externalId: string;
|
||||
// ... other data needed for DB assertions
|
||||
};
|
||||
|
||||
const TEST_VALUES = {
|
||||
// Centralized test data constants
|
||||
};
|
||||
```
|
||||
|
||||
### 3. Local helper functions
|
||||
|
||||
```typescript
|
||||
// Common: open settings and set external ID for DB lookup
|
||||
const openSettingsDialog = async (root: Page) => {
|
||||
await getEnvelopeEditorSettingsTrigger(root).click();
|
||||
await expect(root.getByRole('heading', { name: 'Document Settings' })).toBeVisible();
|
||||
};
|
||||
|
||||
const updateExternalId = async (surface: TEnvelopeEditorSurface, externalId: string) => {
|
||||
await openSettingsDialog(surface.root);
|
||||
await surface.root.locator('input[name="externalId"]').fill(externalId);
|
||||
await surface.root.getByRole('button', { name: 'Update' }).click();
|
||||
|
||||
if (!surface.isEmbedded) {
|
||||
await expectToastTextToBeVisible(surface.root, 'Envelope updated');
|
||||
}
|
||||
};
|
||||
```
|
||||
|
||||
### 4. The flow function
|
||||
|
||||
A single `runXxxFlow` function that works across ALL surfaces. It handles embedded vs non-embedded differences internally:
|
||||
|
||||
```typescript
|
||||
const runMyFeatureFlow = async (surface: TEnvelopeEditorSurface): Promise<FlowResult> => {
|
||||
const externalId = `e2e-feature-${nanoid()}`;
|
||||
|
||||
// For embedded create, may need to add a PDF first
|
||||
if (surface.isEmbedded && !surface.envelopeId) {
|
||||
await addEnvelopeItemPdf(surface.root, 'embedded-feature.pdf');
|
||||
}
|
||||
|
||||
await updateExternalId(surface, externalId);
|
||||
|
||||
// Handle embedded vs native differences
|
||||
if (surface.isEmbedded) {
|
||||
// No "Add Myself" button in embedded mode
|
||||
await setRecipientEmail(surface.root, 0, 'embedded@example.com');
|
||||
} else {
|
||||
await clickAddMyselfButton(surface.root);
|
||||
}
|
||||
|
||||
// ... perform feature-specific actions ...
|
||||
|
||||
// Navigate away and back to verify UI persistence
|
||||
await clickEnvelopeEditorStep(surface.root, 'addFields');
|
||||
await clickEnvelopeEditorStep(surface.root, 'upload');
|
||||
|
||||
// ... assert UI state after navigation ...
|
||||
|
||||
return { externalId /* ... */ };
|
||||
};
|
||||
```
|
||||
|
||||
### 5. Database assertion function
|
||||
|
||||
Uses Prisma directly to verify data was persisted correctly:
|
||||
|
||||
```typescript
|
||||
const assertFeaturePersistedInDatabase = async ({
|
||||
surface,
|
||||
externalId,
|
||||
// ... expected values
|
||||
}: {
|
||||
surface: TEnvelopeEditorSurface;
|
||||
externalId: string;
|
||||
// ...
|
||||
}) => {
|
||||
const envelope = await prisma.envelope.findFirstOrThrow({
|
||||
where: {
|
||||
externalId,
|
||||
userId: surface.userId,
|
||||
teamId: surface.teamId,
|
||||
type: surface.envelopeType,
|
||||
},
|
||||
include: {
|
||||
// Include related data as needed
|
||||
documentMeta: true,
|
||||
recipients: true,
|
||||
fields: true,
|
||||
envelopeAttachments: true,
|
||||
},
|
||||
orderBy: { createdAt: 'desc' },
|
||||
});
|
||||
|
||||
// Assert expected values
|
||||
expect(envelope.someField).toBe(expectedValue);
|
||||
};
|
||||
```
|
||||
|
||||
### 6. The four `test.describe` blocks
|
||||
|
||||
Tests are organized into four `test.describe` blocks, one per editor surface. Each describe block contains the tests relevant to that surface. This structure allows adding multiple tests per surface while keeping them grouped:
|
||||
|
||||
```typescript
|
||||
test.describe('document editor', () => {
|
||||
test('description of what is tested', async ({ page }) => {
|
||||
const surface = await openDocumentEnvelopeEditor(page);
|
||||
const result = await runMyFeatureFlow(surface);
|
||||
|
||||
await assertFeaturePersistedInDatabase({
|
||||
surface,
|
||||
...result,
|
||||
});
|
||||
});
|
||||
|
||||
// Additional document-editor-specific tests here...
|
||||
});
|
||||
|
||||
test.describe('template editor', () => {
|
||||
test('description of what is tested', async ({ page }) => {
|
||||
const surface = await openTemplateEnvelopeEditor(page);
|
||||
const result = await runMyFeatureFlow(surface);
|
||||
|
||||
await assertFeaturePersistedInDatabase({
|
||||
surface,
|
||||
...result,
|
||||
});
|
||||
});
|
||||
|
||||
// Additional template-editor-specific tests here...
|
||||
});
|
||||
|
||||
test.describe('embedded create', () => {
|
||||
test('description of what is tested', async ({ page }) => {
|
||||
const surface = await openEmbeddedEnvelopeEditor(page, {
|
||||
envelopeType: 'DOCUMENT',
|
||||
tokenNamePrefix: 'e2e-embed-feature',
|
||||
});
|
||||
|
||||
const result = await runMyFeatureFlow(surface);
|
||||
|
||||
// IMPORTANT: Must persist before DB assertions for embedded
|
||||
await persistEmbeddedEnvelope(surface);
|
||||
|
||||
await assertFeaturePersistedInDatabase({
|
||||
surface,
|
||||
...result,
|
||||
});
|
||||
});
|
||||
|
||||
// Additional embedded-create-specific tests here...
|
||||
});
|
||||
|
||||
test.describe('embedded edit', () => {
|
||||
test('description of what is tested', async ({ page }) => {
|
||||
const surface = await openEmbeddedEnvelopeEditor(page, {
|
||||
envelopeType: 'TEMPLATE',
|
||||
mode: 'edit',
|
||||
tokenNamePrefix: 'e2e-embed-feature',
|
||||
});
|
||||
|
||||
const result = await runMyFeatureFlow(surface);
|
||||
|
||||
// IMPORTANT: Must persist before DB assertions for embedded
|
||||
await persistEmbeddedEnvelope(surface);
|
||||
|
||||
await assertFeaturePersistedInDatabase({
|
||||
surface,
|
||||
...result,
|
||||
});
|
||||
});
|
||||
|
||||
// Additional embedded-edit-specific tests here...
|
||||
});
|
||||
```
|
||||
|
||||
When a test only applies to specific surfaces (e.g., a document-only action like "send document"), only include it in the relevant describe block(s). Not every describe block needs the same tests -- the structure groups tests by surface, not by requiring symmetry.
|
||||
|
||||
## Key Differences Between Surfaces
|
||||
|
||||
| Behavior | Document/Template | Embedded Create | Embedded Edit |
|
||||
| -------------------------- | -------------------------- | ----------------------------------------- | ----------------------------------------- |
|
||||
| User seeding | Seed + sign in | Seed + API token | Seed + API token + seed envelope |
|
||||
| "Add Myself" button | Available | Not available | Not available |
|
||||
| Toast on settings update | Yes (`'Envelope updated'`) | No | No |
|
||||
| PDF already attached | Yes (1 item) | No (0 items, must upload) | Yes (1 item) |
|
||||
| Delete confirmation dialog | Yes (`'Delete'` button) | No (immediate) | No (immediate) |
|
||||
| DB persistence timing | Immediate (autosaved) | After `persistEmbeddedEnvelope()` | After `persistEmbeddedEnvelope()` |
|
||||
| Persist button label | N/A | `'Create Document'` / `'Create Template'` | `'Update Document'` / `'Update Template'` |
|
||||
|
||||
## Available Fixture Helpers
|
||||
|
||||
### From `fixtures/envelope-editor.ts`
|
||||
|
||||
**Locator helpers** (return Playwright Locators):
|
||||
|
||||
- `getEnvelopeEditorSettingsTrigger(root)` - Settings gear button
|
||||
- `getEnvelopeItemTitleInputs(root)` - Title inputs for envelope items
|
||||
- `getEnvelopeItemDragHandles(root)` - Drag handles for reordering items
|
||||
- `getEnvelopeItemRemoveButtons(root)` - Remove buttons for items
|
||||
- `getEnvelopeItemDropzoneInput(root)` - File input for PDF upload
|
||||
- `getRecipientEmailInputs(root)` - Email inputs for recipients
|
||||
- `getRecipientNameInputs(root)` - Name inputs for recipients
|
||||
- `getRecipientRows(root)` - Full recipient row fieldsets
|
||||
- `getRecipientRemoveButtons(root)` - Remove buttons for recipients
|
||||
- `getSigningOrderInputs(root)` - Signing order number inputs
|
||||
|
||||
**Action helpers**:
|
||||
|
||||
- `addEnvelopeItemPdf(root, fileName?)` - Upload a PDF to the dropzone
|
||||
- `clickEnvelopeEditorStep(root, stepId)` - Navigate to a step: `'upload'`, `'addFields'`, `'preview'`
|
||||
- `clickAddMyselfButton(root)` - Click "Add Myself" (native only)
|
||||
- `clickAddSignerButton(root)` - Click "Add Signer"
|
||||
- `setRecipientEmail(root, index, email)` - Fill recipient email
|
||||
- `setRecipientName(root, index, name)` - Fill recipient name
|
||||
- `setRecipientRole(root, index, roleLabel)` - Set role via combobox
|
||||
- `assertRecipientRole(root, index, roleLabel)` - Assert role value
|
||||
- `toggleSigningOrder(root, enabled)` - Toggle signing order switch
|
||||
- `toggleAllowDictateSigners(root, enabled)` - Toggle dictate signers switch
|
||||
- `setSigningOrderValue(root, index, value)` - Set signing order number
|
||||
- `persistEmbeddedEnvelope(surface)` - Click Create/Update button for embedded flows
|
||||
|
||||
### From `fixtures/generic.ts`
|
||||
|
||||
- `expectTextToBeVisible(page, text)` - Assert text visible on page
|
||||
- `expectTextToNotBeVisible(page, text)` - Assert text not visible
|
||||
- `expectToastTextToBeVisible(page, text)` - Assert toast message visible
|
||||
|
||||
## External ID Pattern
|
||||
|
||||
Every test uses an `externalId` (e.g., `e2e-feature-${nanoid()}`) set via the settings dialog. This unique ID is then used in Prisma queries to reliably locate the envelope in the database for assertions. This is critical because multiple tests run in parallel.
|
||||
|
||||
## Running Tests
|
||||
|
||||
```bash
|
||||
# Run all envelope editor tests
|
||||
npm run test:dev -w @documenso/app-tests -- --grep "Envelope Editor V2"
|
||||
|
||||
# Run a specific test file
|
||||
npm run test:dev -w @documenso/app-tests -- e2e/envelope-editor-v2/envelope-recipients.spec.ts
|
||||
|
||||
# Run with UI
|
||||
npm run test-ui:dev -w @documenso/app-tests -- e2e/envelope-editor-v2/
|
||||
|
||||
# Run specific test by name
|
||||
npm run test:dev -w @documenso/app-tests -- --grep "documents/<id>: add myself"
|
||||
```
|
||||
|
||||
## Checklist When Writing a New Test
|
||||
|
||||
1. Create the spec file in `packages/app-tests/e2e/envelope-editor-v2/`
|
||||
2. Import `TEnvelopeEditorSurface` and the three opener functions
|
||||
3. Import `persistEmbeddedEnvelope` if you need DB assertions for embedded flows
|
||||
4. Define a `FlowResult` type for data passed between flow and assertion
|
||||
5. Define `TEST_VALUES` constants for test data
|
||||
6. Write `updateExternalId` helper (or reuse the pattern)
|
||||
7. Write the `runXxxFlow` function handling embedded vs native differences
|
||||
8. Write the `assertXxxPersistedInDatabase` function using Prisma
|
||||
9. Create four `test.describe` blocks: `'document editor'`, `'template editor'`, `'embedded create'`, `'embedded edit'`
|
||||
10. Place tests inside the appropriate describe block for each surface
|
||||
11. For embedded create tests, add a PDF via `addEnvelopeItemPdf` before the flow
|
||||
12. For embedded tests, call `persistEmbeddedEnvelope(surface)` before DB assertions
|
||||
13. Use `surface.isEmbedded` to branch on behavioral differences (toasts, "Add Myself", etc.)
|
||||
|
||||
## Common Pitfalls
|
||||
|
||||
- **Missing `persistEmbeddedEnvelope`**: Embedded flows don't autosave. You MUST call this before any DB assertions.
|
||||
- **PDF required for embedded create**: Embedded create starts with 0 items. Upload a PDF before navigating to fields.
|
||||
- **Toast assertions in embedded**: Don't assert toasts for settings updates in embedded mode (they don't appear).
|
||||
- **Parallel test isolation**: Always use a unique `externalId` via `nanoid()` so parallel tests don't collide.
|
||||
- **Navigation verification**: Navigate away from and back to the current step to verify UI state persistence (the editor may re-render).
|
||||
- **Delete confirmation**: Native surfaces show a confirmation dialog for item deletion; embedded surfaces delete immediately.
|
||||
Reference in New Issue
Block a user