NetInteractor

A powerful web operation automation library for .NET that enables you to define and execute complex web interactions using simple XML scripts.

🎯 Use Cases

• Web Testing: Automate white-box and integration testing for web applications
• Web Scraping: Extract data from websites using XPath expressions
• Form Automation: Automate form submissions and multi-step workflows
• E-commerce Automation: Automate checkout processes, cart management, and more

✨ Features

• XML-based Scripts: Define web interactions in easy-to-read XML configuration files
• Input Parameters: Pass dynamic values into your automation scripts using $(ParameterName) syntax
• Output Extraction: Extract values from HTTP responses using XPath or Regex
• Flow Control: Conditional execution with if statements
• Reusable Targets: Define named targets and call them from other targets
• Modern HTTP Client: Uses HttpClient for better performance and reliability
• Cross-Platform: Supports .NET Standard 2.0, .NET 8.0, and .NET 9.0
• Browser Automation: Optional Playwright integration for JavaScript-rendered pages

📦 Installation

Install via NuGet Package Manager:

dotnet add package NetInteractor

For browser automation with JavaScript rendering, also install the Playwright package:

dotnet add package NetInteractor.Playwright

Or via the Package Manager Console:

Install-Package NetInteractor

🚀 Quick Start

1. Create an XML Script

Create a configuration file (e.g., Shop.config) that defines your web interaction workflow:

<InteractConfig defaultTarget="BuyItem">
    <target name="BuyItem">
        <!-- Navigate to product page -->
        <get url="http://www.example-shop.com/product/12345" />
        
        <!-- Add item to cart -->
        <post clientID="cart-form">
            <formValue name="size" text="Medium" />
            <formValue name="quantity" value="1" />
        </post>
        
        <!-- Verify cart contents -->
        <get url="http://www.example-shop.com/cart">
            <output name="totalPrice" 
                    xpath="//span[@class='cart-total']" 
                    attr="text()" 
                    expectedValue="$28.00" />
        </get>
        
        <!-- Checkout with payment details -->
        <post clientID="checkout_form">
            <formValue name="billing_name" value="$(FullName)" />
            <formValue name="email" value="$(Email)" />
            <formValue name="credit_card" value="$(CreditCardNumber)" />
            <formValue name="exp_month" value="$(CreditCardExpMonth)" />
            <formValue name="exp_year" value="$(CreditCardExpYear)" />
        </post>
    </target>
</InteractConfig>

2. Execute the Script

using NetInteractor;
using NetInteractor.Config;
using NetInteractor.WebAccessors;
using System.Collections.Specialized;

// Load the configuration
var config = ConfigFactory.DeserializeXml<InteractConfig>("Scripts/Shop.config");

// Create the executor with an HTTP client accessor
var webAccessor = new HttpClientWebAccessor(new HttpClient());
var executor = new InterationExecutor(webAccessor);

// Prepare input parameters
var inputs = new NameValueCollection
{
    ["FullName"] = "John Doe",
    ["Email"] = "john@example.com",
    ["CreditCardNumber"] = "4111111111111111",
    ["CreditCardExpMonth"] = "12",
    ["CreditCardExpYear"] = "2027"
};

// Execute the automation
var result = await executor.ExecuteAsync(config, inputs);

// Check results
if (result.Ok)
{
    Console.WriteLine("Automation completed successfully!");
    
    // Access extracted output values
    foreach (var key in result.Outputs.AllKeys)
    {
        Console.WriteLine($"{key}: {result.Outputs[key]}");
    }
}
else
{
    Console.WriteLine($"Automation failed: {result.Message}");
}

3. Using Playwright for JavaScript-Rendered Pages

For websites that require JavaScript rendering (e.g., SPAs, dynamic content), use the Playwright web accessor:

using NetInteractor;
using NetInteractor.Config;
using NetInteractor.WebAccessors;

// Load the configuration
var config = ConfigFactory.DeserializeXml<InteractConfig>("Scripts/Shop.config");

// Create the executor with a Playwright accessor for JavaScript support
await using var webAccessor = new PlaywrightWebAccessor();
var executor = new InterationExecutor(webAccessor);

// Execute the automation (same as before)
var result = await executor.ExecuteAsync(config, inputs);

Note: Playwright requires browser binaries. Run playwright install chromium to install the required browser.

📖 Script Reference

Actions

| Action | Description | |--------|-------------| | <get> | Performs an HTTP GET request | | <post> | Submits a form via HTTP POST | | <if> | Conditional execution based on parameter values | | <call> | Calls another target by name |

GET Action

Navigates to a URL and optionally extracts output values:

<get url="http://example.com/page">
    <output name="title" xpath="//h1" attr="text()" />
    <output name="price" xpath="//span[@class='price']" attr="text()" expectedValue="$10.00" />
</get>

POST Action

Submits a form with the specified values:

<!-- By form client ID -->
<post clientID="login-form">
    <formValue name="username" value="$(Username)" />
    <formValue name="password" value="$(Password)" />
</post>

<!-- By form index (0-based) -->
<post formIndex="0">
    <formValue name="search" value="query" />
</post>

<!-- By form name -->
<post formName="contactForm">
    <formValue name="message" value="Hello!" />
</post>

Output Extraction

Extract values from responses using XPath or Regex:

<!-- XPath extraction -->
<output name="productName" xpath="//div[@class='product-title']" attr="text()" />

<!-- Extract attribute value -->
<output name="imageUrl" xpath="//img[@id='product-image']" attr="src" />

<!-- With expected value validation -->
<output name="status" xpath="//span[@class='status']" attr="text()" expectedValue="Success" />

<!-- Regex extraction -->
<output name="orderId" regex="Order #(\d+)" />

<!-- Multiple values -->
<output name="allPrices" xpath="//span[@class='price']" attr="text()" isMultipleValue="true" />

Conditional Execution

Execute actions conditionally based on parameter values:

<if property="PaymentMethod" value="CreditCard">
    <post clientID="credit-card-form">
        <formValue name="card_number" value="$(CardNumber)" />
    </post>
</if>

Reusable Targets

Define and call reusable targets:

<InteractConfig defaultTarget="Main">
    <target name="Login">
        <post clientID="login-form">
            <formValue name="username" value="$(Username)" />
            <formValue name="password" value="$(Password)" />
        </post>
    </target>
    
    <target name="Main">
        <!-- Call the Login target -->
        <call target="Login" />
        
        <!-- Continue with other actions -->
        <get url="http://example.com/dashboard" />
    </target>
</InteractConfig>

🔧 Configuration Reference

InteractConfig Attributes

| Attribute | Description | |-----------|-------------| | defaultTarget | The name of the target to execute by default |

Target Attributes

| Attribute | Description | |-----------|-------------| | name | Unique identifier for the target |

FormValue Attributes

| Attribute | Description | |-----------|-------------| | name | The form field name | | value | The value to set (supports $(param) syntax) | | text | Alternative to value for setting field text |

🏗️ Architecture

NetInteractor
├── Config/           # XML configuration models
├── Interacts/        # Action implementations (Get, Post, If, Call)
├── WebAccessors/     # HTTP client abstractions
├── InteractExecutor  # Main execution engine
└── ConfigFactory     # XML deserialization

📋 Requirements

• .NET Standard 2.0+ / .NET 8.0+ / .NET 9.0+
• Dependencies:
  • HtmlAgilityPack (HTML parsing)
  • Microsoft.Extensions.Logging (Logging support)
  • Microsoft.Extensions.DependencyInjection (DI support)
• Optional Dependencies (for browser automation):
  • Microsoft.Playwright (NetInteractor.Playwright package)

📄 License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📬 Contact

• Author: Kerry Jiang
• Repository: https://github.com/kerryjiang/NetInteractor